5 ms·
Well-written article with examples, screenshots, going into the specifics of what makes a project documentation great for users/developers/contributors. It mad
by lioeters 3y ago
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 3y agoThe tools for this should be better. I wish that Literate Programming was more widespread: http://literateprogramming.com/ http://literateprogramming.com/ Currently trying to arrive at a good toolchain for my own efforts: https://willadams.gitbook.io/design-into-3d https://willadams.gitbook.io/design-into-3d and https://github.com/WillAdams/gcodepreview https://github.com/WillAdams/gcodepreview and at this time, the best option is looking like: https://quarto.org/ https://quarto.org/ and TeXshop and probably .dtx files (but if someone has a better suggestion, I'd be open to it).
- Onawa 3y agonbdev is a mixture of Quarto and Jupyter and targets the exact use case you're talking about. https://nbdev.fast.ai/ https://nbdev.fast.ai/
- metaed 3y agoI 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 3y agoIf you're looking for essentially a modern LaTeX, you might enjoy https://github.com/typst/typst https://github.com/typst/typst
- WillAdams 3y agoI'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.
- ies7 3y agoI 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 3y agohttps://diataxis.fr/ https://diataxis.fr/