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.
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.
//docs/development/starnix/._toc.yaml file. For more information, see Updating site navigation and TOC files.For more information on creating documentation, see Contributing to documentation
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.
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.
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.