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 (www).

Documentation Structure

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:

  • cs and 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. en/forms/rendering.texy.
  • URLs are concise, e.g. page “Atomic Operations” is located at doc.nette.org/en/atomicity.
  • URLs are written in English and they are the same across all localizations, e.g. doc.nette.org/cs/forms/rendering and doc.nette.org/en/forms/rendering.

Contributing

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 nette/docs repository.