[HN Gopher] Two open source projects with great architecture doc...
       ___________________________________________________________________
        
       Two open source projects with great architecture documentation
        
       Author : johnjago
       Score  : 77 points
       Date   : 2024-03-25 17:58 UTC (5 hours ago)
        
 (HTM) web link (johnjago.com)
 (TXT) w3m dump (johnjago.com)
        
       | johnjago wrote:
       | I 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?
        
       | gurjeet wrote:
       | Postgres project also pays great attention to detail when it
       | comes to documentation, readme files, and code comments.
        
       | lioeters wrote:
       | 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.
        
       | xbar wrote:
       | "The biggest deficiency in the free software community today is
       | not in the software--it is the lack of good free documentation
       | that we can include with the free software."
       | 
       | - gdb manual
        
         | mjw1007 wrote:
         | When was "today" when that was written?
        
       | pbnjay wrote:
       | As a counterpoint/opportunity... what are some great open source
       | projects (e.g well-used/adopted) that do NOT have great docs?
        
       ___________________________________________________________________
       (page generated 2024-03-25 23:00 UTC)