Notes on Technical Writing

A lot of technical writers focus on the style of the text. For example, I&#x27;ve seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization.<p>I wish tech writers would channel their focus elsewhere:<p>- If you haven&#x27;t got it working, don&#x27;t document it. Getting information by talking to SWEs is not enough. Your docs will lack depth and preciseness, and it will show. A lot.<p>- Show fully qualified imports in code samples. If you don&#x27;t know what that is, ask SWEs. Given a computer with installed dependencies (such as Maven, Pip, npm, etc.), even your (grand)mother should be able to follow the docs.<p>- Create automated testsuide for your code samples.<p>- Mandate that lack of docs be a blocker for a release.<p>When there are docs written in perfect style and English, yet none of the code samples works, or when I have to spend 30 minutes finishing the &quot;obvious&quot; parts of the code to get it to work, that&#x27;s when I get really frustrated.<p>The article seems to be deeply focused on the style. I can&#x27;t remember when I got frustrated with documentation because the style was bad, or because the sentences were too long.

When I first saw the title I thought to myself, “shit, another random, possibly misleading post about technical writing?” but on quick review this seems to be a well-researched overview of the field. If you were to ask a practicing technical writer to present a summary like this, it wouldn’t differ much.<p>If the author is here, I’m curious if they took that definition of technical writing from my post? [1] To the best of my memory I feel like I came up with that definition on my own but also wouldn’t be surprised if I subconsciously took it from somewhere else.<p>[1] <a href="https:&#x2F;&#x2F;kayce.basqu.es&#x2F;blog&#x2F;metrics&#x2F;" rel="nofollow">https:&#x2F;&#x2F;kayce.basqu.es&#x2F;blog&#x2F;metrics&#x2F;</a>

&gt; In this time, I’ve read various resources on technical writing and documentation. These are my notes, both to help me remember later, but also as a tool to help me think about writing now.<p>and later, in an apparent contradiction ...<p>&gt; You don’t need to tell the reader what you’re going to tell them. Just tell them.<p>I think this point could be fleshed out better.<p>Any piece of nonfiction writing, technical or otherwise, that doesn&#x27;t give me a clear idea about its content may not pass my filter. I see this the most in long-form journalism. But it also pops up when authors focus on themselves, their struggles, and their aspirations in the first couple of paragraphs.<p>Telling the reader what they&#x27;re about to read in the first paragraph of a technical piece is a courtesy. People are busy, and they don&#x27;t have time to wade through a bunch of throat-clearing at the start of a piece. They&#x27;ll just close the tab and move on.

I always try to understand the readers before writing a word. Why they are reading. And what they expect to be able to do better as a result of reading, or what decision they might be making.<p>If an author can&#x27;t answer these questions, they will likely write something that is perceived as irrelevant, wrong, or simply &#x27;meh&#x27;. This is especially true when writing &#x27;technical reports&#x27; as opposed to documentation.

&quot;Don’t tell the reader something is extremely complex; likewise don’t tell the reader something is simple. The reader will make up their own mind about a concept being easy or hard.&quot;<p>I think this is great advice, and applied to teaching. I can&#x27;t tell you the number of times a professor has said &quot;and then obviously it follows that&quot; or &quot;it&#x27;s easy to see that&quot;. Nearly every time that was uttered in a lecture I wanted to hurl my textbook at the board.<p>Looking for alternatives? &quot;Is it easy?&quot; or &quot;It might be obvious&quot; work fine. Maybe use those moments as opportunities to check in with your audience. In the written context, maybe offer end&#x2F;footnotes explaining why it might be obvious&#x2F;easy.

Most documentation is so bad and so often out-of-date that I can answer my question faster by reading the source (or tests).<p>Everything is so extremely verbose. I don&#x27;t want to read a 7 paragraph essay about how this or that feature was developed and evolved over time; I just need a one line hint and maybe an example. Believe it or not, your software is not special. We&#x27;ve seen something like it before and get the gist already. I like the style of man pages, where everything is on one page and organized by the flag, i.e. actual usage (puts a hard limit on meandering bullshittery).

This is well done!<p>&gt; Support error recognition and recovery.<p>I totally agree with this. You have to teach critical concepts a couple different ways in case one gets skimmed over or misunderstood. We rely on visuals for this--the text should stand independent of the photo &#x2F; diagram, and vice versa.<p>I wrote a handbook on technical writing summing up what we&#x27;ve learned over many years of writing iFixit repair guides. <a href="https:&#x2F;&#x2F;help.dozuki.com&#x2F;Tech_Writing&#x2F;chapter&#x2F;0" rel="nofollow">https:&#x2F;&#x2F;help.dozuki.com&#x2F;Tech_Writing&#x2F;chapter&#x2F;0</a>

Tech Writing is a waterfall job.<p>What&#x27;s needed is something more like peer review, where the &quot;tech writer&#x27;s&quot; job is to ask hard question from the user POV during development - for varying values of &quot;user&quot;, which would include customer, API consumer, and so on.<p>This wouldn&#x27;t be code review, because it&#x27;s about features, interfaces, and expected behaviours, not the fine details of implementation. And it wouldn&#x27;t be a PM job, because it would be peer feedback in the form of dialog, not management in the form of requirements and specs.<p>And it should be continuous, so the doc base evolves in parallel with the code base.<p>And it should not be an afterthought.<p>This job does not exist yet. And it should, because virtually all orgs have a problem where individual developers become repositories of The Important Knowledge. If they leave it becomes hard to characterise system behaviours and architectures well enough to understand how they work well enough to replace&#x2F;improve&#x2F;reverse engineer them.<p>So IMO there&#x27;s a niche for people who are competent developers, competent listeners, and competent communicators, who can pull it all together, stay on top of changes, and leave a readable record of the current state of institutional knowledge about projects, practices, stacks, and interfaces.

I worked on designing and implementing a data architecture at a FAANG. One of the things we found worked well was bringing documentation as close as possible to source - that way, making changes to one but not the other has a high rate of getting caught during code reviews and documentation stays in sync. The challenge with this approach was then accessibility for non technical customers who don’t care for nor have reason to look at source. Instead of building documentation pages, we leveraged a system that was a registry of datasets, individual columns, use cases, and sample queries... it was tricky to get right but we implemented a pipeline where documentation from code would get propagated to this system automagically.<p>In terms of general technical writing, style is less of a concern I have. The real challenge is writing efficiently to convey sufficient information to the audience, without staying too high level but also not providing too many details. I often suffer from writers blockz

Anyone know where I can get legit technical writing gigs? I used to get paid to write about Elasticsearch for a company&#x27;s blog and that was pretty cool. Would be keen to do something like that again. I can write about anything in the sysadmin&#x2F;devops space or in the penetration testing space. Thanks

I actually found this article a bit confusing to read. I suppose they are &quot;notes&quot; but I found myself having to reread stuff a few times and it wasn&#x27;t organized in a particularly clear way.<p>Here are some notes I had:<p>This is a very weird sentence:<p>&gt; In the 1980s, they developed a minimalist approach and created a wonderful Operator Training Manual for the IBM Displaywriter, imagine having to introduce someone to using a word processor for the first time.<p>There is also a misspelling in &quot;the four principals of minimalist instruction&quot;.<p>In that same section it is confusing to bullet point the four principles but include a summary of the principle at the end of the bullet point. This makes it hard to skim. (It&#x27;s also self-referential, which the previous section recommends against.)

I’m a software engineer, but I have a degree in English lit. I find I love technical writing. Maybe it’s because I’m often writing about systems I built, so I understand them well and the writing comes fluidly — it might be less fun to write about systems I don’t know as well. Still, I find technical writing one of the parts of my job I most look forward to: presenting to my colleagues a proposed implementation, for example, is both a social aspect of engineering and a way to make sure your design is comprehensible and hence simple (simplicity being a hallmark of good design). I tend not to stress too much over whether I’m writing well: the goal is just to communicate ideas, after all, not to make art.

At the end of this article the author links to and mentions the four types of technical documentation: <a href="https:&#x2F;&#x2F;www.divio.com&#x2F;blog&#x2F;documentation&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.divio.com&#x2F;blog&#x2F;documentation&#x2F;</a><p>I’ve found this to be especially useful when writing documentation. If you don’t think in this way them your documentation may end up being an impromptu blend of more than one type, and hence may not be useful for a specific use case. Instead I try to structure the documentation for one of these.

These are great notes!<p>I’ve been writing for years, but I am constantly finding out that I still have a long way to go.<p>Thanks!

The third section advises to avoid meta writing. So... get rid of the first two paragraphs of this article?