Contributing to Documentation

Contributing to the documentation is one of the most valuable activities, as it helps others understand the framework.

How to Write?

Documentation is primarily intended for people who are new to the topic. Therefore, it should meet several important points:

  • Start with simple and general concepts. Move on to more advanced topics only at the end.
  • Try to explain the topic as clearly as possible. For example, try explaining it to a colleague first.
  • Provide only the information that the user actually needs for the given topic.
  • Verify that your information is accurate. Test every piece of code.
  • Be concise – cut what you write in half. Then feel free to do it again.
  • Use highlighting sparingly, from bold text to boxes like .[note].
  • Follow the Coding Standard in the code examples.

Also, learn the syntax. To preview the article while writing, you can use the preview editor.

Language Versions

English is the primary language, so your changes should ideally be in English. If English is not your strong suit, use DeepL Translator and others will review your text.

Translation into other languages will be done automatically after your edit is approved and finalized.

Trivial Edits

To contribute to the documentation, you need to have an account on GitHub.

The easiest way to make a small change in the documentation is to use the links at the end of each page:

  • Show on GitHub opens the source version of the page on GitHub. Then just press the E key to start editing (you must be logged in to GitHub).
  • Open preview opens an editor where you can immediately see the final visual appearance.

Since the preview editor cannot save changes directly to GitHub, after finishing your edits, you need to copy the source text to the clipboard (using the Copy to clipboard button) and then paste it into the editor on GitHub. Below the editing field is a submission form. Here, don't forget to briefly summarize and explain the reason for your edit. After submitting, a pull request (PR) is created, which can be further edited.

Larger Edits

Instead of relying solely on the GitHub interface, it's better to be familiar with the basics of working with the Git version control system. If you're not familiar with Git, you can refer to the git – the simple guide and consider using one of the many available graphical clients.

Edit the documentation as follows:

  1. On GitHub, create a fork of the nette/docs repository.
  2. Clone this repository to your computer.
  3. Then, make changes in the appropriate branch.
  4. Check for extra spaces in the text using the Code-Checker tool.
  5. Save (commit) the changes.
  6. If you are satisfied with the changes, push them to GitHub to your fork.
  7. From there, submit them to the nette/docs repository by creating a pull request (PR).

It is common to receive comments with suggestions. Keep track of the proposed changes and incorporate them. Add the suggested changes as new commits and push them to GitHub again. Never create a new pull request just to modify an existing one.

Documentation Structure

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

The content of each branch is divided into main folders representing individual documentation areas. 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 language versions (cs, en, …) and optionally a files subfolder with images that can be included in the documentation pages.

  1. Documentation
  2. Become a Contributor to Nette
  3. Contributing to Documentation