Documentation

What is wrong with the current compile lifecycle? It is slow. When developing, I value fast feedback. Immediate feedback. The faster I can see where my code is broken, the faster I can fix it. But currently there’s a 3-step process for this feedback: Modify code Run checks/lints/tests or examples Apply fixes Step 2 is usually the time-consuming part, since it requires compiling the code, linking it, running the tests, etc. This breaks my development flow. ...

How can we improve developer documentation? More thoughts on improving the documentation process and experience: A core issue with documentation is that it does not answer the right questions. Oftentimes, there is documentation, but it only rehashes the code, without adding any value, or describes some irrelevant aspect. My hypothesis is that by applying Question-Driven Documentation (QDD), i.e using questions as headings, and letting them drive the documentation process, we can improve the quality of the documentation. ...

What’s wrong with developer documentation? I have been thinking a lot lately about developer documentation and from my perspective, there are two main issues with it from my experience: It’s hard to find the relevant documentation for a piece of code. The documentation is outdated, and does not reflect the current state of the code I feel that often #2 is a direct consequence of #1. How do we fix this? Here’s my simple pitch to address these issues: ...