Writing Documentation

Contributing to documentation is one of the most rewarding activities because you help others understand the framework.

Quick Edits

The easiest way to edit the text in the documentation is to use the links at the bottom of each page:

  • Show on GitHub opens the source version of the page on GitHub. Then just press the E button and you can start editing (you must be logged in to GitHub)
  • Open preview opens the editor, where you can also see the resulting visual form.

Since the preview editor does not have the ability to save changes directly to GitHub, you must copy the source text to the clipboard (using the Copy to clipboard button) and then paste it into the GitHub editor when you are done editing. Below the edit box is a form to submit. Be sure to briefly summarize and explain the reason for your edit here. Once submitted, a pull request will be created that can be edited further.

How to Write?

The documentation is mainly for people who are new to the topic. Therefore, it should meet several important points:

  • When writing, start from the simple and general. Move on to more advanced topics at the end.
  • Include only the information that the user really needs to know about the topic.
  • Verify that your information is actually true. Test the code first before giving it.
  • Be concise – reduce what you write by half. And then do it again.
  • Try to explain the matter as well as you can. For example, try explaining the topic to a colleague first.
  • Spare the highlighters of all kinds, from bold type to boxes like .[note].

Keep these points in mind throughout your writing. Get to grips with syntax too. You can use a preview editor to preview the article as you write it.

In addition to the above points, also observe the following guidelines:

  • English is the primary language, so your changes should be in both languages. If English is not your strong point, use DeepL Translator and others will proofread your text.
  • Follow the Coding Standard in the examples.
  • Write variable, class and method names in English.
  • Namespaces should be given at the first mention.
  • Try to format your code so that scroll bars are not displayed.
  • For documentation, refer only to the documentation or www.

Contributing to the Documentation

You must have a GitHub account to contribute to the documentation. You can make simple changes directly in its interface.

However, it is more useful to know the basics of working with the Git versioning system. If you're not familiar with Git, you can check out this quick guide: git – the simple guide, or use one of the many graphical tools: GIT – GUI clients.

Start edit the documentation by creating a fork of the nette/docs repository and cloning that onto your computer. Then make changes in the appropriate branch, commit the change, push to your GitHub repository, and send a pull request to the original repository nette/docs.

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

Documentation Structure

All documentation is hosted on GitHub in the nette/docs repository. The current version is in the master, older versions are located in branches like doc-3.x, doc-2.x.

The content of each branch is divided into main folders representing each area of the documentation. For example, application/ corresponds to https://doc.nette.org/en/application, latte/ corresponds to https://latte.nette.org, etc. Each of these folders contains subfolders representing the language versions (cs, en, …) and possibly a subfolder files with images that can be embedded in the documentation pages.

  1. Documentation
  2. Get Involved in Improving Nette
  3. Writing Documentation