-
Notifications
You must be signed in to change notification settings - Fork 23
Conventions
To maintain some consistency in our documentation and ensure everyone can work as smoothly as possible, here are a few rules to follow when contributing documentation to Chamilo.
Make sure you use the correct branch. If unsure, send a Pull Request (a special contribution flow) to master and tell us you don't know, so we can explain how to do that towards the right branch (or we can even do that ourselves). This will also help us know if you can manage Pull Requests or not.
We use the Markdown format, which is a bit easier to understand than HTML, but a bit more complex than simple text.
There are currently 3 possible guides: Teacher, Admin and Developer. These should (ideally) be split in the 3 following folders in the Git branch:
- teacher-guide/
- admin-guide/
- developer-guide/
A special folder (.gitbook/assets/) has been reserved for icons and images of all kinds. Please use it to upload all images you need. In the future, we might add more separation between icons and screenshots, for example, or between icon formats, but this is not yet the case.
For all icons to be inserted in the documentation, we would love to use icons in the SVG format (if you import them from Chamilo 1.11, you will find most icons are available in the SVG format in main/img/icons/svg/) but sadly, Gitbook (which we use to display our manuals) does not support SVG resizing well enough, so temporarily, we use the PNG format in 32px width, resized to 20px through img tags (see below).
If you absolutely want to use SVG, please be aware that the default of SVG icons in Chamilo will usually display them in ~128px width and height, which requires your icon to be shown outside of the text block (which can still work).
For icons inserted inside a block of text, please use a size of 20px as otherwise they show up too big on most displays.
When using SVG or PNG, one issue that might arise is that it is not well sized initially and you might need to force resizing, which you cannot do in the Markdown format. To avoid this issue, please use the following HTML format:
<img src="../../.gitbook/assets/folder.png" width="20" style="margin-bottom:-3px;">
The margin-bottom and width part is specific to icons inserted inside a block of text. You don't need these if the icon is shown by itself in a block.
Considering icons are only a visual helper for people who will use those icons, an alt attribute should never be useful for icons inserted in text blocks. However, if an icon is put in evidence as its own block, please add an alt attribute to describe it.
Please try to use same icon names as in Chamilo. If, for some reason, this is a new icon, please use lowercase split by underscores.
DO NOT use parenthesis and spaces.
AVOID using numbers if possible.
Please use the PNG format. Alternatively, you can use the WebP format, but PNG is just fine and better supported for most uses.
For screenshots, please resize your screenshots to 1200px width. We also invite you to reduce the colours palette to a web-focused 255 colours palette, and to compress them to the maximum (compression of "9").
Screenshots are inserted in a pretty standard Markdown format like the following. We use an "Illustration" label directly stuck to the screenshot tag to ensure it is associated with the image. Gitbook seems to have a hard time showing these properly, but this is consistent in the Markdown format. The same title as is inside the Illustration suffix can be used as "Alt" at the beginning of the tag.
{Some text}
_Illustration 91-9: Export results_
{Some more text}
Please make sure you leave one blank line before the image tag, one blank line between the image tag and the legend, and one blank line after the legend and before any following text. If you don't do it this way, the screenshot and the legend will appear next to one another on https://docs.chamilo.org, considerably reducing the size of the screenshot and making it practically useless in its offline form.
Considering the fact there is no global management of images, and despite the fact that you will find most historical files contain numbering, we ask you NOT TO NUMBER your illustrations, as it only generates issues when inserting a new block somewhere.
In fact, don't use numbering anywhere.
Try naming your screenshots in lowercase filenames with underscores splitting words. The names parts should be from the highest categorization to the lowest. If your screenshot is about reports (object) on users (topic), with special time features, you could call it "user_reports_time_based_display.png", for example.
The filename will not be visible from the manual directly. However, other contributors to the manual might save considerable time if they need a screenshot that already exists, and will find them more easily if they are named properly.
Don't try to generate series of things. Don't put numbers on chapters or on illustrations, as it creates more maintenance complexity without clear benefit in the context of the Chamilo manuals.
If you work on a long-standing file that has numbering in it, please don't hesitate to remove it.