Guidelines

Table of content:

Guidelines.

To create a new tutorial, use the Create Tutorial item in the Content Writers menu on the left.

Good, accessible tutorials and documentation do for a software project what education does for a society. It fuels the exchange of skills, strenghten the community and broaden the project horizons. To write a piece of documentation, writers need some communication and writing skills. They need to foresee where readers are likely to get stuck in an explanation. Or what piece of information is the most useful among all the options available. Writers need not only directly related information on the subject but background knowledge and references as well, when a particular technique is based on external research or common standards used across all render engines. Our main recommendations are:

  • Plan in advance the structure of your writing.
  • Gather some previous information. Ask for help if needed.
  • Use paragraphs.
  • Be concise.
  • Write not about settings and buttons but about features and concepts involved. It is better and your writing will be less likely to become outdated.
  • Test the boundaries of the feature you are writing about.
  • Use lists of items whenever is possible (like this one).
  • Always include visual information to support your explanations about a visual effect.
  • Structure your work in sections and subsections. Use headings for each of them.
  • Give to your document a table of content and link it to anchors in headings.
  • Give a copyleft to your work.
  • Rewiew your work and seek for improvements.
  • Cite your references. Respect other people's work and copyright.

About FAQ

FAQs should be based on usual questions posted in the community forum. Answer in Frequent Answered Questions should be short and straight to the point. As explained in this section, you can add images to support your explanation, but use small snapshots of 200x200 pixels, so we can keep a dynamic look in the FAQ section, with a quick succession of FAQs. It's also a good idea to add related links to support your explanation.

Remember to select FAQ type in the second field from the top, either User FAQ or Developer FAQ, so the Frequent Answered Question is linked to the right menu section.

Document format.

  • Paragraph is the standart default body format.
  • Use Heading 2, Heading 3 and Heading 4 for formating sections and subsections headers. (Heading 1 is reserved for the page header).
  • Just write the heading line, select it and go to the 'Format' menu on the left, and select a suitable heading type.
  • Use <var> when you refer to a button on the interface (select text first).
  • Use <code> when you refer to a piece of code, a directory or a text terminal command. (select text first)

Adding images to your documents.

These are the main steps to add images to support your explanations:

To add images, go to 'File attachements' at the bottom of the edit page, and attach an image as a file. When a image is uploaded, a small link will appear below the 'Description' field, copy it (Ctrol+C). Uncheck the List box so the image is not attached as a file.

Then open the 'Inser/edit image' feature, and paste the link (Ctrol+V) in the 'Image URL' field, and click on Insert. The image will appear in your document. The images can be scaled up and down regardless of the original size, by using 'Inser/edit image', then 'Appereance' section.

550 px. is the max. safe width for images, use 250x250 for snapshots.

Example of an attached image on the left, using the steps explained above. Resolution is 250x250 pixels. In this case, a table has been used as well to divide the vertical space between image and text.

Adding files to your documents.

Adding files is like adding images, use 'file attachments' feature at the bottom of the edit page. Once the file is uploaded, save your document and the file download link will appear at the bottom of the document. In this case, the List box must be checked on for attached files to appear.

Editing and saving documents.

When a tutorial is saved, a node link is assigned to the tutorial, but it does not appear in the site structure yet. It needs approval and manual linking by administrators, so it is publicly available for the whole community. Anyway, the tutorial is available for editing in the Tutorial queue section on the left, till is approved. Use the Edit button (at the top of the page) to edit the tutorial. We'll wait till is finished, but you can contact us in the chat room if you have any question or you want to make us some comments about your work.

Once a tutorial is finished and approved by the administrators, it will be linked to the Documentation > Tutorials section of this site. Edit button is available for authors even if a tutorial is already published, so you can improve or update it later on the road.

Thanks for your collaboration! :D