[HN Gopher] Product docs alongside product code
       ___________________________________________________________________
        
       Product docs alongside product code
        
       Author : PatrickHeneise
       Score  : 13 points
       Date   : 2021-06-24 19:04 UTC (2 days ago)
        
 (HTM) web link (opstrace.com)
 (TXT) w3m dump (opstrace.com)
        
       | polote wrote:
       | I agree that technical docs should be the closest to the code.
       | But one problem of that is docs is more difficult to discover. As
       | you need to browse the repo and docs is in the middle of source
       | code.
       | 
       | What I tried to do, is to use Github API to list all .md files in
       | a repo and index them as if they were Confluence/Notion/.. docs
       | (with tags, attributes, folders, ...). One issue, there is not a
       | lot of granularity in the permission system of github, and the
       | app would need to have a view right on all files of each repo,
       | which can be an issue when you offer this app as Saas. Same this
       | is not possible to share only one file of a repo with an external
       | app
        
       | personjerry wrote:
       | As a PM, I thought this was about documenting the details of
       | features and their functionality. I recently joined a startup
       | with no documentation at all, and I spent a great deal of time
       | documenting how everything worked. Even then, I kept being
       | surprised by new functionality.
        
       | pyronicide wrote:
       | I've always wanted a setup like this! It is so much easier to
       | author docs when you can tie them directly to functionality and
       | manage through PRs.
       | 
       | How are you planning on managing the publishing workflow for non-
       | devs? Marketing and docs teams tend to struggle quite a bit with
       | git specific flows.
        
       ___________________________________________________________________
       (page generated 2021-06-26 23:01 UTC)