Our great sponsors
-
lowdefy
The config web stack for business apps - build internal tools, client portals, web apps, admin panels, dashboards, web sites, and CRUD apps with YAML or JSON.
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
MarginaliaSearch
Internet search engine for text-oriented websites. Indexing the small, old and weird web.
-
documentation-framework
"The Grand Unified Theory of Documentation" (David Laing) - a popular and transformative documentation authoring framework
I strongly back the Divio system for documentation, it works great. But you should know that the creator of the system doesn't work at Divio anymore and the newest iteration is now called Diataxis https://diataxis.fr/
100% this. And yes, good documentation takes a lot of investment but it pays off like compound interest. But with that done, it becomes even more important not to pull the carpet for no good reason, you are building a tower and documentation is at the foundation.
We’ve built Lowdefy [1] as an open source project and documented it with all effort, 200 pages of docs. I often forget why or how something works and then jump to the docs. This investment keeps on paying of as we use Lowdefy to build customer apps, new devs in the team typically take less than two week to get up to speed and start making contributions, the sharp ones, just a two or three days.
This year, we’re extended our documentation onto customer apps aswell, with flow diagrams, state machine definitions, detailed field level explication schema definitions, and end user test procedures. The key here for this documentation is detail. It should be easier to reach for the docs and the the answer, than to dive in the code and interpret it.
1 - https://github.com/lowdefy/lowdefy
Problem with documentation is that there are a lot of uses for documentation. It can be a reference, it can describe the architecture, it can do many things. Probably a good idea to figure out what the intent is first to find a good form.
Some of my stuff is pretty sprawling, I've started integrating the documentation with the code and basically use readme.md's littered in the code as sign-posts to let you navigate it more quickly. The intent of that documentation is pretty clear, and the shape follows logically.
e.g. https://github.com/MarginaliaSearch/MarginaliaSearch/tree/ma...
Reminds me of the four types of documentation that sometimes get listed: tutorials, how-to guides, technical reference and explanation. (Usual caveat of all models are wrong but some are useful.) https://documentation.divio.com/
My (perhaps overly simplistic) take would be that we should take the thinking we use on the product itself (Who's going to use it? In what context? What would they already know? And so on), and apply and adapt it to the docs as we would any other product.