[HN Gopher] The Seven-Action Documentation Model
       ___________________________________________________________________
        
       The Seven-Action Documentation Model
        
       Author : remoquete
       Score  : 62 points
       Date   : 2025-01-09 13:18 UTC (9 hours ago)
        
 (HTM) web link (passo.uno)
 (TXT) w3m dump (passo.uno)
        
       | adolph wrote:
       | Link going next to Diataxis [0] in my bookmarks.
       | 
       | 0. https://diataxis.fr/
        
         | remoquete wrote:
         | Hi there! I'm the author of the Seven-Action Docs Model.
         | 
         | Big yes. I think the 7A model is fully compatible with the
         | likes of Diataxis, or with pragmatic initiatives such as The
         | Good Docs Project [1].
         | 
         | 1. https://www.thegooddocsproject.dev/
        
       | asdfman123 wrote:
       | > A solution to this situation is shifting the focus from what
       | should be written to what user needs should be addressed
       | 
       | This goes for all forms of communication, all the time. Whether
       | you're writing or speaking or having an informal conversation,
       | relentlessly focus on your audience: what they think, what they
       | know, and what they need to hear.
       | 
       | Think hard about your audience, and then think about them again.
       | 
       | Oh, also my soapbox topic is all documentation should have a line
       | at the top explaining it like you'd explain it to your parents.
       | "This cli tool was built in order to automatically run all tests
       | in the suite, instead of manually like before." Etc.
        
         | smartmic wrote:
         | If you do not know your audience, think of yourself as the
         | primary audience. There is no shame in writing as if the
         | recipient is your (past or future) self. This has nothing to do
         | with ego, but with clarity and self-reflection. After all, you
         | should know yourself best.
        
         | euroderf wrote:
         | > a line at the top explaining it like you'd explain it to your
         | parents
         | 
         | Another benefit of this is that in a complex environment, this
         | helps the user check that they have the correct manual, so they
         | don't waste their time trying to absorb it for no good purpose,
         | realizing only some time later that it was some other manual
         | that they wanted.
        
           | asdfman123 wrote:
           | Yes, thank you. I hate reading things like:
           | 
           | > The whizbanginator facilitates workflows with reductive
           | conflapitance. Here's some info about its release cycle and
           | on call. Here are all of its configuration details, which
           | will make you realize it does not actually solve your
           | problems because we never told you what it was.
        
       | hitchstory wrote:
       | >Engineers dabbling in documentation and feeling lost as they
       | approach the field, on the other hand, are drawn to docs
       | frameworks because frameworks are all they're used to working
       | with
       | 
       | Im drawn to frameworks because without them I cannot implemented
       | an automated way to address the problem of docs going out of
       | date.
        
         | remoquete wrote:
         | Docs frameworks (conceptual, theoretical ones) don't really
         | solve the problem of docs going stale. Better processes and
         | hiring tech writers do.
        
       ___________________________________________________________________
       (page generated 2025-01-09 23:00 UTC)