Writing Documentation
It will be great, if you will participate in making or translating the documentation. And how?
You must have a permission to edit the documentation, you can ask for it on the forum. If are are not sure with something, just write to the Documentation section.
How to write?
Documentation is primarily intended for people who are just learning the
topic. Be aware of that for the whole writing. Text should be written from
simple things to complicated things. There's no need to say every detail
immediate in the introduction (and especially not using agressive
.[note] notes), we don't want to glut our reader.
Simplicity is appreciated. Whatever you write, reduce it by half. And if you are done with that, reduce it by half again.
Explainability is appreciated. Before you start to write, try to explain that topic to your colleague (or dog) and then start to write it.
- Learn how to use syntax, you can try it in the sandbox, where you can make no harm
- Follow Coding Standard
- Use English names of variables, classes and methods
- Write everything for version of the Nette Framework 2.0 and PHP 5.3 (with the exception for 0.9 documentation)
- We are using warnings (
.[warning]) when writing about differences in versions of 5.2 and 5.3 in framework itself (except namespaces) - Class names with their namespaces use just in the first mention, then use class names without namespaces
- Take care of all highlighters, from bold font to
.[note]frames - We use “we” in the text of documentation, and we are polite
- Perex is a simple trailer of the topic, it's not a first paragraph
- Try to format your code to don't use scrollbars
- Layout of the page should be well-arranged, use empty rows between paragraphs, titles, sources, etc.
- When you are done, visit Documentation translation
status and change status from
TranslatedtoTranslated - not acctual.
How to make a translation?
Home page of English documentation is prepared, you just have to fill in a content. It's now displayed as a translation using Google Translator, so don't be confused. The simplest way is to copy the source code from a Czech page and use it as a base of your English page. You can use Google Translator to pre-translate that source code, but don't forget to change changes in wiki syntax, which were made by translation process.řeložit Google Translatorem, jen je potom potřeba upravit změny, které udělá ve wiki syntaxi.
Translation should use simple vocabulary, because it's intended not only for native speakers, but for everyone.
Before you start, write yourself to Documentation translation status, to avoid translating something what is already in translation process, or something what is not in a final phase.