Starnix is a complicated component with many subtle aspects to its development. Starnix is also a part of the codebase that many people need to work on, even if they are not on the Starnix team itself. Rather than teaching each of these subtle aspects to each person individually, we should create more documentation and refer people to that documentation more often. Hopefully, people will look for information in docs, which will cause us to write more documentation, creating a virtuous cycle.
Answer questions with documents
Whenever the Starnix team receives a general question about how Starnix works or how to develop Starnix, we should answer that question by writing some documentation covering that topic and then refer the person asking the question to that documentation. This approach creates the illusion of perfect documentation coverage because the documentation is created "just in time" to meet the needs of people asking questions.
This approach will result in many small fragments of documentation, which will not be well-integrated into a whole. As these fragments accumulate, we should refactor them into more comprehensive, better organized documentation. This refactoring process is easier than writing documents from scratch because the goal is not to add more information to the documentation, but to improve the organization of the existing information.
Practical steps
- Identify the question: When you type a paragraph explaining a complex topic in chat, stop.
- Create a file: Create a file in
//docs/development/starnix/. - Paste and polish: Paste your explanation. Add a title and a sentence of context.
- Update TOC: Add an entry for your new document in the
_toc.yamlfile. For more information, see Updating site navigation and TOC files. - Publish: Upload a CL. Send the link to the requester.
- Refactor later: Don't worry about where it fits perfectly. Getting the knowledge into the repo is the priority.
For more information on creating documentation, see Contributing to documentation
Imperfect documents
A rough, but focused document is better than no document. Don't worry if the document is short or doesn't cover every possible edge case. If you are answering a specific question, you can use the question as the title of the document.
Organization
When creating a new document, you don't need to worry about finding the perfect
place for it in the documentation hierarchy. It is fine to add the file to the
top-level starnix directory or a generic concepts directory. As we accumulate
more documents, we can organize them into a more structured hierarchy.
Coding agents
As a byproduct, this approach will also produce documentation that is useful to coding agents working on our codebase. These coding agents benefit from this documentation even more than humans because coding agents have more difficulty asking live questions to humans.