1

Writing Good Documentation

Profile picture
Mid-Level Software Engineer at Taro Community4 months ago

How can I create well-structured documentation that is easy to read and provides background information for the audience? What strategies or methodologies can help ensure clarity and accessibility?

Is there a good template that works 100% of time ?

55
3

Discussion

(3 comments)
  • 1
    Profile picture
    Engineer @ Robinhood
    4 months ago

    I've written thousands of lines of code of payments related code for a high-traffic financial company (with a few attempts earlier in my career to actively "document" code) and the best way I found to document my code was to:

    1. Write better code. Good code is easy to read. If engineers can read the code, why document it? Good code is self documenting.
    2. Write better commit comments. A good commit message and a good PR review gives me all of the context I need on who wrote the commit's code, what were they thinking, and who reviewed it. Traditional documentation doesn't really do that for me.

    What generally needs documention for me though is the high-level of a feature or a product. High level behavior is less susceptible to change and is harder to understand (since it's built from many layers of code), so documentation is more valuable here (it grows stale slower & the information exposed is time-intensive to get). A good eng design doc will do the job here: bonus points if an engineer links the design doc in every commit/PR to implement that design doc.

  • 0
    Profile picture
    Mid-Level Software Engineer [OP]
    Taro Community
    4 months ago

    To add to above question:

    How do I determine what content is essential to include in the documentation, especially when unsure of the audience’s background knowledge? What strategies can help assess the right level of detail without overwhelming the audience?

    • 0
      Profile picture
      Engineer @ Robinhood
      4 months ago
      • Your goal to writing documentation is to suppliment the reader's development in the code. There are mainly 2 reasons I write documentation. First is to explain the context and/or line of thought that lead me to the code (if I feel like the past context is important for understanding the code in the present). Second is to provide a high level summary of what the code does if I feel like the code will take too much time to read & scroll through.
      • My hot take is that if someone is trying hard to document as much as they can: that's not a documentation issue. That's a skill issue with the developer being bad at writing code.