Building Key Habits for Technical Writing (And More): Part 1

A sneaky problem I’ve met in tech consulting is how issues and statuses — and knowledge in general — can get siloed between a few stakeholders when a wider broadcast could be more beneficial.

There aren’t always huge consequences but I’ve sometimes seen it lead to repeat work, rushed triage/solutions, technical debt, more meetings😱 and budget overruns.

Methodologies can look to head off these drains, but another great way I’ve found to be proactive and protective of your team is to build or contribute to an existing knowledge base.

Here I’ll talk about some methods that helped me transform short notes taken in my day-to-day into a bevy of artifacts including end-user guides, SDK/technical documentation, templates, training materials, branding/styling protocols and even a QA test suite. Hope it helps!

Document as You Go

Building the mindfulness to take notes may take awhile but I first made it a habit to write down steps I was taking in real time. This doesn’t only help to retrace, replicate and QA a solution: These notes can be spruced up and serve as the basis to be packaged into a reusable asset for your team or client.

What I Used: Apple Notes

Know the Prerequisites

Would a team member or external stakeholder have all the necessary components to make it through a guide of yours?

A chef may require a knife as much as ingredients so be sure to identify the tools required to help a reader reproduce your instructions. This could range from IDEs and package downloads to having admin permissions. I found it helpful to spell these out right at the top.

What I Used: Prerequisite checklists

Add Visual Flourishes

I mostly produced documentation in SharePoint, which offers a collection of widgets to drag-and-drop in site building. Knowing this, I stayed cognizant of when to take a screenshot or even screen record a complex set of steps. Code snippets or even a set of zipped up code files linked right on a page can also make your reader’s lives better.

And for other collateral such as a PowerPoint, there are platforms such as Canva to add creatives to a company template!

What I Used: SharePoint widgets

Organized Storage

This will be personal to each writer, but creating a classification system and grouping your notes and assets (locally or version control) in recording tasks will help keep order when there’s no time to produce documentation right away.

Fact-Checking

This is from my journalism days but getting an edit will keep your documentation honest. Validate your work and get a senior colleague or subject matter expert to eyeball your article, or let a teammate put the steps through the wringer.

For internal docs, I’d also list myself — and anyone involved with the subject/article — as resources that other teammates could contact.

Version Control/Reiterate

Ensure you have a source of truth and version control on as documentation should be updated and maintained for accuracy. Big feature pushes can change a whole lot, which means your documentation must potentially change a whole lot!

For Part II, I’ll aim to get into writing structures and tenets!