[lioeters]

Well-written article with examples, screenshots, going into the specifics of what makes a project documentation great for users/developers/contributors.

It made me reflect on my own work and side projects, how I could improve the docs to make things easier to understand for myself and others. As I've grown as a developer, I've been writing more and more documentation, same with tests, to a point where some projects have more tests and docs than the actual code itself.

I've heard it said that writing good documentation requires a different set of skills than writing code. Sometimes a person who is not technical or focused on development can be better at explaining things. At the least it requires a different perspective, to target the human runtime.

I'll also add that automatically generated docs can be very useful, not by themselves only, but as an additional reference.

[WillAdams]

The tools for this should be better.

I wish that Literate Programming was more widespread:

http://literateprogramming.com/

Currently trying to arrive at a good toolchain for my own efforts: https://willadams.gitbook.io/design-into-3d and https://github.com/WillAdams/gcodepreview and at this time, the best option is looking like:

https://quarto.org/

and TeXshop and probably .dtx files (but if someone has a better suggestion, I'd be open to it).

[metaed]

I take a minimalist approach. Any project goes in a single .nw file, formatted for Noweb, edited using Vim. I use a source highlighter that recognizes multiple languages in a single buffer. Noweb generates all my objects, including program text, makefiles, tests, and all documentation. Building the project is just "noweb *nw" followed by "make".

[yencabulator]

If you're looking for essentially a modern LaTeX, you might enjoy https://github.com/typst/typst

[WillAdams]

I've spent a lot of time using LaTeX, and just purchased the two volume _The LaTeX Companion: 3rd Edition_ --- I've tried more LaTeX replacements than I would care to count and --- still holding out for LaTeX3, we'll see.

[Onawa]

nbdev is a mixture of Quarto and Jupyter and targets the exact use case you're talking about. https://nbdev.fast.ai/

[ies7]

I use concept from diataxis.fr

> Diátaxis is a way of thinking about and doing documentation.

> It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.

[remram]

https://diataxis.fr/