Contributing to Documentation

Contributing to 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 topics. Move on to more advanced topics at the end
  • Try to explain the topic as clearly as possible. For example, try explaining the topic to a colleague first
  • Only provide information that the user actually needs to know for a given topic
  • Make sure your information is accurate. Test every code
  • Be concise – cut what you write in half. And then feel free to do it again
  • Use highlighting sparingly, from bold fonts to frames like .[note]
  • Follow the Coding Standard in the code

Also, learn the syntax. For a preview of the article during writing, you can use the preview editor.

Language Mutations

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

Translation into other languages will be done automatically after approval and fine-tuning of your edit.

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 button and you can start editing (you must be logged in to GitHub)
  • Open preview opens an editor where you can immediately see the final visual form

Because the preview editor does not have the ability to save changes directly to GitHub, 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 form for submission. Here, don't forget to briefly summarize and explain the reason for your edit. After submitting, a so-called pull request (PR) is created, which can be further edited.

Larger Edits

It is more appropriate to be familiar with the basics of working with the Git version control system rather than relying solely on the GitHub interface. If you're not familiar with Git, you can refer to the git – the simple guide and consider using one of the many graphical clients available.

Edit the documentation in the following way:

  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 resend them to GitHub. 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 areas of documentation. For example, application/ corresponds to https://doc.nette.org/cs/application, latte/ corresponds to https://latte.nette.org, etc. Each of these folders contains subfolders representing language mutations (cs, en, …) and optionally a files subfolder with images that can be inserted into the pages in the documentation.

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