Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Two open source projects with great architecture documentation

johnjago.com

Post reply on HN
Print view View original

31–38 of 38 posts

Re: Two open source projects with great architecture documentation

#31

Post by Onawa »

WillAdams wrote: post #11
lioeters wrote: post #4

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 h…

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 sugg…

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 documentation

#32

Post by metaed »

WillAdams wrote: post #11
lioeters wrote: post #4

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 h…

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 sugg…

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 documentation

#33

Post by yencabulator »

WillAdams wrote: post #11
lioeters wrote: post #4

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 h…

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 sugg…

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 documentation

#34

Post by godshatter »

eliasson wrote: post #20

Antirez (redis creator) has written a good post [1] detailing his thoughts on code comments where he identifies nine type of comments used in Redis. What surprised me was the use of "guide comments" which most people dismiss as too trivial. I agree with Antirez conclusion that they are valuable to help the reader acknowledge their understanding of the code. [1] http://antirez.com/news/124

I like guide comments because they show intent and because if you're scanning a function in an editor where comments stand out visually then it gives you a quick recipe of what the function nominally should be doing, which helps when you're trying to come up to speed in a code base.

They are even more useful if the author hates whitespace and tries to be too clever. I spend a lot of time trying to figure out code someone else wrote and appreciate anything that can set me in the right direction when trying to figure out what a particular function does.

Re: Two open source projects with great architecture documentation

#35

Post by WillAdams »

yencabulator wrote: post #33
WillAdams wrote: post #11

Earlier quoted context omitted.

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 sugg…

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

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.
Post reply on HN