Writing the Documentation

Contributing to the documentation is one of the many ways you can help Nette. It is also one of the most rewarding activities, as you help others understand the framework.

How to Write?

The documentation is primarily intended for people who are just getting familiar with the topic. Therefore, it should meet several important points:

  • When writing, start with the simple and general, and move to more advanced topics at the end.
  • Provide only the information that the user really needs to know about the topic.
  • Verify that your information is actually true. Test the example first before giving the example.
  • Be concise – cut what you write in half. And then feel free to do it again.
  • Try to explain the matter as well as possible. For example, try explaining the topic to a colleague first.

Keep these points in mind throughout the writing process. The documentation is written in Texy!, so learn its syntax. You can use the documentation editor at https://editor.nette.org/ to preview the article as you write it.

Among the general writing rules listed earlier, please stick to the following:

  • Your code should be in compliance with the Coding Standard.
  • Write the names of variables, classes and methods in English.
  • Namespaces need only be mentioned at first mention.
  • Try to format the code so that scroll bars are not displayed.
  • Spare all kinds of highlighters, from boldface to .[note] boxes.
  • From the documentation, refer only to the documentation or www.

Documentation Structure

The full documentation is hosted on GitHub in the nette/docs repository. This repository is divided into branches based on the version of the documentation, for example the doc-3.1 branch contains the documentation for version 3.1. And then there is the nette.org branch, which contains the content of the other subdomains of nette.org.

Each branch is then divided into several folders:

  • cs and en: contains documentation files for each language version
  • files: images that can be embedded in the documentation pages

The path to a file without an extension corresponds to the URL of a page in the documentation. Thus, the file en/quickstart/single-post.texy will have the URL doc.nette.org/en/quickstart/single-post.

Contributing

To contribute to the documentation, you must have an account at GitHub and know the basics of Git. If you're not familiar with Git, you can check out the quick guide: git – the simple guide, or use one of the many graphical tools: GIT – GUI clients.

You can make simple changes directly in the GitHub interface. However, it is more convenient to create a fork of the repository nette/docs and clone it to your computer. Then make changes in the appropriate branch, commit the change, push to your GitHub, and send a pull request to the original nette/docs repository.

Before each pull request, it's a good idea to run Code-Checker to check extra whitespace in the text.