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
anden
: contains documentation files for each language versionfiles
: 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.