Documentation

Documentation Best Practices & Advices that work for me

Last Updated: September 17, 2025 by Pepe Sandoval

Want to show support?

If you find the information in this page useful and want to show your support, you can make a donation

Use PayPal

or

Donate with Crypto

This will help me create more stuff and fix the existent content...

Why don't we like to document? 🤔

  1. Documentation trauma from school where it meant big long reports, lots of text that you are never going to read again

  2. The idea that ALL that matters is the code, the algorithm, the implementation, the actual functionality

  3. We are just lazy but then this usually means more work later, because we don't even remember how to run something we coded/created

  4. Document stuff is a drag

    • "Documentar da hueva"

Good Abstraction = Good Documentation

  1. I don't document for my manager, nor for my peers, nor for other people in general, I document for myself so I can be lazy and work less later

    • I document now so I can be lazy later

    • The most efficient way of being lazy is to document

  2. I automate so I can work less tomorrow

    • What can I document today so I can work less tomorrow?
    • After I document then I can more easily automate

What I do NOT recommend

  1. Keep things ONLY in your brain
Only in my mind

  1. Think steps to install requirements or setup something are not as important as actual app

  2. Put something on a personal folder

    • \\10.122.10.64\share\pepeuser\my_script.py

  3. Think that because it works on your computer it will work anywhere

    • You need to have clear steps to reproduce somewhere else

  4. Keep things ONLY on an email thread, a chat, or other service where things can easily get lost among the sea of other stuff

  5. Think that once you have something that works that means you are done

    • Code completion is only half the work

  6. Let 'future you' worry about something

I'll do it later
  1. Thinks stuff will not come for you
It wont' come for me

  1. Think that lots of comments and text is good documentation

  2. Think that every API and line of code needs to be documented and/or commented

    • NO! instead create a simple test showing how your API/code works

What I recommend

  1. Be concise

    • Think of ways to synthesize the info you document (a table, a diagram, a test, etc.)

  2. Have specific examples

  3. Find a format/tool that clicks for you but I recommend something that can be easily searchable

    • Markdown
    • Wikis
    • OneNote
    • Loop

  4. (Optional) Find an organization method that clicks/works for you

    • PARA: Projects, Areas, Resources, Archives
    • By Topic Categories and sub-categories
    • By Projects you work on

  5. ALWAYS Create good abstractions

    • Examples of good abstractions:
      1. One-liners
      2. Something I can copy paste hit enter and get a result
      3. CSR = Clone-Setup-Run:
        • 1 command to clone
          • git clone my_repo
        • 1 command to setup
          • pip install requirements.txt
          • python setup.py
          • make install
        • 1 command to run the most basic example
          • python my_script.py --help
          • make test
          • ./my_script -h

  6. Document how to run the most basic example/test of your code

  7. Have a quick start guide or abstract with only the commands

  8. Put stuff in a place where you can easily share them and track changes

    • A repo
    • An asset on services like Artifactory
    • A link to public shared folder

  9. In Jira or work tracking systems prefer update over add

    • Nobody likes to scroll until the end of times
    • Have a comment and edit with latest update

  10. Document how to run the most basic example/test of your code

  11. Have a quick start guide or abstract with only the commands

  12. Document thinking on your "future you" (be nice to him/her)


Documentation prompts

We have tech...
  1. Generate table from arguments

generate a table in markdown raw text explaining these input arguments

  1. Create "how-to" guide for readme.md

Generate a "How-to" guide in markdown showing step by step how to run this script, include steps to: clone repo, install requirements and command that shows an example of how to run the script, you can leave placeholders for the specific URLs and resources you cant infer

Want to show support?

If you find the information in this page useful and want to show your support, you can make a donation

Use PayPal

or

Donate with Crypto

This will help me create more stuff and fix the existent content...