2. Maharaドキュメンテーション執筆者のための情報

This is a list in progress as I work on the documentation. There are a number of things for which I create conventions. I want to keep them in a central space so that others have access to them and that I can refer to them as well. ;-)

このリストは特定な順序に並んでいません。

  • Screenshots are placed as figures and always include alt text and a figure description. The latter will receive numbering in the PDF export.

  • 使用されている警告:

    • 注意: やや注意が必要なものです。
    • warning: for anything that needs to be done with caution
    • seealso: for references to other documents if they need special attention. References to other documents can also be included in the text inline.
    • todo: for keeping a running ToDo list

  • 保存 または ページをコピーする およびポートフォリオセクションの コンテンツ、ポートフォリオ 等のボタンはテキストを強調するために「*」マークを使ってハイライトされています。

  • Little buttons can be included in the text.

  • Screenshots of Mahara sections are not made inline, but receive the 「figure」 directive. They always have an alt tag and also a brief description which will show up below the image and is numbered in LaTeX PDF.

  • Screenshots should have as little instructions as possible about the steps that are to be taken in them. Preferably, only the step numbers so that they can be exchanged more easily and the text of the steps is translatable because it is text and not part of the image. That could also mean that translators can translate the steps but don’t immediately have to change the screenshot.

  • Inline images that are refered to in the textsuch as edit should be included as shortcuts with the reference at the bottom of the page.

  • それぞれのセクションにインデックスエントリを作成してください。

  • 編集時に操作しやすいように長いセクションは複数ページに分割されています。

  • reStructuredText does not have a set hierarchy of heading levels. They depend on the individual files. However, to be consistent, the following convention exists:

    • 見出し1 例) 1.: ===============
    • 見出し2 例) 1.1.: —————
    • 見出し3 例) 1.1.1.: ~~~~~~~~~~~~~~~
    • 見出し4 例) 1.1.1.1.: ^^^^^^^^^^^^^^^

  • h4以下の見出しは避けるべきです。

  • I create screenshots with Shutter in Ubuntu. It is easy to add the callouts which indicate the steps to take. However, any other screenshot software can be used. Preferably, the callouts look similarly. The color is #4C711D.

  • The callouts in the screenshots refer to the steps that need to be taken.

  • Screenshots should only show the necessary area and not the entire screen or URL address bars etc. where not necessary.