Juha-Matti Santala
Community Builder. Dreamer. Adventurer.

Blog posts in category “Documentation”

These are the blog posts that are about documenting technical things.

  • Jun 5th, 2024
    Make ripples through time and space by writing

    Documenting your experiences, knowledge and learnings can have a big positive impact to others - including the future you.

  • Apr 6th, 2024
    Markdown - the trade-offs of simplicity

    I love the simplicity of Markdown. I’m also very frustrated by the simplicity of Markdown. It’s so good for certain things but then falls off too hard when the limits are reached.

  • Mar 6th, 2024
    Chesterton’s Fence and tech documentation

    A principle from public policy is a great source of inspiration for writing good documentation that captures the reasons for decisions.

  • Feb 12th, 2024
    Public notes

    Public notes are a great way to document a process of doing something while sharing it with others so they can learn too.

  • Oct 4th, 2023
    Document your secrets

    We’ve become quite good as industry in avoiding leaking our secrets through version control. But we might have stepped one step too far and have ended up with .env.sample files that have nothing but environment variable names.

  • Jul 19th, 2023
    What tech docs can learn from video game tutorials?

    Video games are well known for their tutorials and how they teach increasingly complex actions to players step by step. Technical documentation and tutorials can learn quite a bit from the video game industry.

  • Jun 21st, 2023
    Give your commands consistent names

    A discussion in fediverse lead me to a wonderful path to learn about different approaches people have to wrap different software development commands behind unified interface.

  • Jun 14th, 2023
    Document outdated components

    When your codebase evolves iteratively instead of everything at once, you end up with components or files that use outdated style and should not be used as an example for future code. Document those cases to avoid problems.

  • May 31st, 2023
    Writing documentation is a great tool to improve software quality

    During my last journey into documentation, I once again discovered how great tool writing can be for crafting better software.

  • Apr 26th, 2023
    How to document a workaround?

    As developers, we sometimes run into a situation where something is wrong and its not within our reach. A bug in a library, a mishap in an integration or something else. You need a short-term workaround. It's important to document them so you can eventually get rid of them.

  • Apr 20th, 2022
    Documentation: man pages vs tldr

    How do reference and recipe documentation approaches differ and where they shine? Let's take a look by comparing man pages to tldr pages.

  • Apr 21st, 2021
    Documentation-driven command line tools in Python with docopt

    One way to power your Python command line tool's argument parsing is to use documentation-driven approach and use docopt library.