6. Document authoring and translation

Members can write web contents, manuals, and HOWTOs. We write documents in Japanese first and report so to members-ML, asking the Project's translators to do the translation. Nevertheless, the original can be of course written in English.

For the document format and writing style, please refer to Document-HOWTO.

6.1. Group and privilege

Document writers and translators are in the following group:

Group Privilege
www can checkout and commit the www repository

The weboperator group exists apart from the www group. This is the group which has a rebooting authority of httpd for checking the normal renewal of www contents. (see : Section 8.1, “Group and privilege”)

In addition, any member in momonga group can checkout and commit to the docs repository. This means any member account holder can checkout and commit to the documents.

6.2. Updating the web contents

When you changed the contents, do the following locally:

      $ xmllint --noout --valid HOGE-HOWTO.xml
      $ make
and make sure that there is no error messages or warnings from it before you do commit. Please proofread the produced HTML files and text files.

Web contents are updated hourly by cron. In case your document modification is not reflected to the contents, slogin to the server and do the following to see if there have been any errors:

    $ sudo  /etc/cron.hourly/webupdate.hourly

Alternatively, you can sudo -u momonga make under the directory /home/momonga/html. To avoid errors during updating, check your document before you commit. For example, you may want to do the following before committing your changes:

    $ xmllint --noout --valid Hoge-HOWTO.xml

6.3. What to write in a HOWTO

It may be the case that the difficulty you had to run a program can be the same trouble other people may be experiencing. If a HOWTO is at hand, it sure will make a great assistance. Please turn your trouble experience into a form that may help others.

6.4. Points of attention

  • Please unify style and punctuation within a document.

  • Please use Kanji (Chinese characters) for words that are usually written in Kanji. (Of course this doesn't apply for English documents :)

  • Please keep updating promptly the portion where correction and updating are needed.

  • Please do not use GIF files for picture. Use PNG files instead.