Blog posts in category “Documentation”
These are the blog posts that are about documenting technical things.
-
Apr 6th, 2024Markdown - 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, 2024Chesterton’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, 2024Public 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, 2023Document 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, 2023What 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, 2023Give 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, 2023Document 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, 2023Writing 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, 2023How 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, 2022Documentation: 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, 2021Documentation-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.