Skip to content
TechDug

@dig-log

TechDug Editors

The house journal of TechDug. Notes from the editors on writing technical posts that work: reproducible steps, copyable commands, clear error write-ups and honest updates.

Posts
10
Writing since

Start here

An introduction from TechDug Editors

We are the editors of TechDug. This journal is where we write down what we look for when we read a technical post: steps that work on a clean machine, commands that paste cleanly, errors explained properly and posts that stay accurate after the tools move on.

Start here:

  1. How to write a tutorial someone else can reproduce
  2. Code blocks readers can copy and paste safely
  3. How to explain an error message in a post
  4. Updating a technical post without breaking trust
  5. Writing a README that answers the first questions

For what the platform itself provides, see the features and the publishing guidelines.

Posts

10 posts

  1. Writing a 'why we chose X' post engineers can trust

    State the constraints, the alternatives you honestly considered, what you gave up, and what would make you reconsider: a trustworthy decision post.

    5 min read

  2. Writing a migration guide readers can trust

    Say who it applies to, give a check for who is affected, prove the backup, verify every step and test the way back: a guide people can safely follow.

    6 min read

  3. Explaining a shell pipeline one stage at a time

    Show the finished command, give readers the input, then add one stage at a time with its output. A log-counting pipeline as the worked example.

    6 min read

  4. Writing a bug report maintainers can act on

    A clear title, exact versions, a five-line reproduction, expected versus actual, full output and what you tried: a bug report that gets picked up.

    6 min read

  5. Writing a changelog people actually read

    Group changes by what they mean, write entries for users not committers, flag breaking changes with migrations, and link every release to its diff.

    6 min read

  6. How to write a tutorial someone else can reproduce

    Clean machines, recorded versions, pinned installs and expected output: a checklist for tutorials that still work for a reader who is not you.

    5 min read

  7. Code blocks readers can copy and paste safely

    No prompts in the block, output kept apart, placeholders that fail loudly and no curly quotes: conventions for commands people will actually paste.

    5 min read

  8. How to explain an error message in a post

    Quote it exactly, say which program is talking, give the cause, the fix and a check, then cover the near misses. A Python import error as the example.

    5 min read

  9. Updating a technical post without breaking trust

    A tested-with line, dated change notes, stable addresses and your own Git history: how to revise a technical post so readers can still rely on it.

    5 min read

  10. Writing a README that answers the first questions

    What it is, who it is for, how to install it on a clean machine and what success looks like: a README outline you can copy and cut down to size.

    5 min read