Writing the Documentation
Writing the documentation is one of many ways you can help the Nette Framework. Additionally, it is one of the most helpful contributions, as you are helping others to learn the framework.
Rules of Writing
The main audience of the documentation is people who are new to the topic. The text of the documentation should comply with the following rules:
- Start with the simple and common topics, write about the more advanced topics at the end.
- Omit the unnecessary information.
- Verify your facts. Test your code before writing an example.
- Be concise. Halve you text, then halve it again.
- Be explanatory. Try explaining the topic to your colleague first.
Keep these rules in mind when you are writing. The documentation is written in Texy!, so have a look at its syntax. You can use documentation editor at https://editor.nette.org/ to preview your article. This editor also provides live preview.
Among the general writing rules listed earlier, please stick to the following:
- Your code should be in compliance with the Coding Standard.
- Use English names for variables, methods and classes.
- Include the namespaces only on the first mention.
- Try to keep lines of code short and fit them into width of text without scrolling.
- Use highlighting only when necessary.
- Link only to the documentation itself or to the main website (
The documentation is stored at GitHub in the nette/docs repository. This repository
has several branches according to the version of Nette. For instance, branch
doc-2.1 corresponds to the Nette
Framework version 2.1.
Each branch has several directories:
en: contains documentation files for each localization.
files: images, that can be inserted into pages.
File path without the extension matches the page URL on the website. File
en/quickstart/single-post.texy will have
the URL of
quickstart/single-post in the corresponding version of the English documentation.
Keep the following rules in mind when creating new pages:
- Maximum depth of the URL is 2, not counting the language, e.g.
- URLs are concise, e.g. page „Atomic Operations“ is located at
- URLs are written in English and they are the same across all localizations, e.g.
To contribute to the documentation, an account at github.com is required. You also need to know the basics of git version control system. For an quick introduction you can see git – the simple guide, or use one of many graphical clients: GIT – GUI clients.
Before contributing, create your own fork of the
nette/docs repository and clone it. Make the changes in the
correct branch and commit them. Then push the repository to github.com and send a pull request to the original
The coding standard also complies with the documentation. It is good to run nette/code-checker before every pull request, preferably before pushing to repository, which will check all the coding standards.