Re:Two open source projects with great architecture document...
by WillAdams on Monday March 25, 2024 @09:32PM
(#39823401)
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:
and TeXshop and probably .dtx files (but if someone has a better suggestion, I'd be open to it).
Re:Two open source projects with great architecture document...
by Onawa on Tuesday March 26, 2024 @10:43AM
(#39828554)
nbdev is a mixture of Quarto and Jupyter and targets the exact use case you're talking about. https://nbdev.fast.ai/
Re:Two open source projects with great architecture document...
by metaed on Tuesday March 26, 2024 @11:28AM
(#39829132)
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".
Re:Two open source projects with great architecture document...
by yencabulator on Tuesday March 26, 2024 @01:30PM
(#39830514)
If you're looking for essentially a modern LaTeX, you might enjoy https://github.com/typst/typst
Re:Two open source projects with great architecture document...
by WillAdams on Tuesday March 26, 2024 @03:07PM
(#39831611)
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.
Re:Two open source projects with great architecture document...
by ies7 on Monday March 25, 2024 @10:53PM
(#39823863)
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.
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.