Available translations
loading results
Documenting New Projects
Summary: Producing original documentation of new features or entirely new projects is a bit challenging. It requires a good understanding of the Docs infrastructure, and of how the existing documentation is built.
Interview the Developers
The first requirement is to fully understand what the new project or feature is about. The best approach is to interview the developers involved while recording the session on video.
The developers should explain the new features conceptually, explain how things work, and even demo the features in a dedicated workspace. Make sure you cover what each node in each of the new hierarchies represents and how they work, as you will need to produce individual definition pages for each node.
Tip: Schedule as many interviews as required. Complex functionality may require several sessions.
The video recordings will help you go back and review everything that was discussed. This is crucial, as you will probably not understand all the details during the live session, and will likely need to mature the concepts as you write.
Also, you may contribute the video material to the Superalgos Youtube Channel, or publish the content on your channel too.
Start With Definitions
The very first writeups you will produce are the pages corresponding to each new node type involved. We call these the Definition Pages, as each page defines precisely what each node represents, how it works, and how it relates to other nodes.
Important: It may not be apparent why you should start with definitions, but I assure you it's crucial, mainly for two reasons!
- Writing the definition of each node will help you understand each piece of the puzzle in sufficient detail so that you may grasp all the nuance in the overall behavior of the hierarchy. This level of understanding is crucial to figuring out what is the best way to explain the whole project or feature.
- Pretty much like each node in a hierarchy is a piece in a puzzle of the new project or feature, each definition page is a piece in the puzzle of the documentation. In other words, a documentation Topic is comprised mostly of Definition Pages. I will expand on this later on.