This shows that the maintainers really care about the quality of their repository.
Two open source projects with great architecture documentation
21–30 of 38 posts
Re: Two open source projects with great architecture documentation
#22Antirez (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
The Laravel source code is an impressive example of that.
Re: Two open source projects with great architecture documentation
#23As a counterpoint/opportunity… what are some great open source projects (e.g well-used/adopted) that do NOT have great docs?
Gradle for sure
Re: Two open source projects with great architecture documentation
#24I feel like GitLab's docs have a reputation for being very good but I haven't had much need to use them myself. Would you consider their architecture docs good?
Ehm, their docs are an example of a case when stackoverflow answers provide better docs than the official pages. To put it politely.
Re: Two open source projects with great architecture documentation
#25I was particularly impressed by the first one, esbuild. The architecture documentation is so thorough—it’s something I would have loved to have for codebases I’ve worked on in the past. Does anyone have other examples of projects with this level of architecture documentation?
I wonder if the diagrams were done in Figma? Diagrams are probably the #1 thing missing from most docs, and they are hard / time-consuming to make
They do look very nice
The author of esbuild was also the CTO/main author of Figma, as far as I understand
Re: Two open source projects with great architecture documentation
#26As a counterpoint/opportunity… what are some great open source projects (e.g well-used/adopted) that do NOT have great docs?
React, especially React Native.
There are lots of docs, and in most cases the quality at some point was good, but they're often out of date, and old versions hang around for a long time. Real world projects often use wildly different versions of React (because it's hard to keep up with the version churn) so I guess all those different doc versions are necessary.
For React Native, the docs are missing detail so you have to look at the code, and the code comments were pretty spotty and inconsistent the last time I looked.
Re: Two open source projects with great architecture documentation
#27As a counterpoint/opportunity… what are some great open source projects (e.g well-used/adopted) that do NOT have great docs?
SDL2 docs are not amazing, but the project itself is an incredible achievement of cross platform development.
Agreed to both.
That brings Three.js to mind, that's another terrific project with patchwork docs.
Re: Two open source projects with great architecture documentation
#28Another example of great documentation is Vue.js one [1].
Re: Two open source projects with great architecture documentation
#29Documenting projects and situations in general is so underrated. Don't need to go overboard, but a good foundation for understanding streamlines so many things in the end. Good read.
Re: Two open source projects with great architecture documentation
#30As a counterpoint/opportunity… what are some great open source projects (e.g well-used/adopted) that do NOT have great docs?
SDL2 docs are not amazing, but the project itself is an incredible achievement of cross platform development.
The bespoke SDL docs aren’t too good but the header files have great documentation.