Get started with technical writing

I had an idea 10 years ago to hire a bunch of English majors as interns for the summer to bootstrap a big technical writing project, but that got shut down almost immediately. No engineer values tech writers, because they envision themselves as large great white sharks, and the tech writers to them are just bottom feeders that exist in their ecosystem.

That said, I managed to rewrite 800 pages of small bank management documentation into 600 pages of well-formatted, _readable_ manual. I don't know if it was worth it, I was in Lincoln, NE and I didn't have anything better to do. I dropped the readability statistics from freshman in college to freshman in high-school and I'm sure the customer was more the latter than the former. Not to judge, I never met a customer that wasn't worth helping.

Am I especially good at writing? Not in my opinion. You'll quickly find it is a target rich environment. The manual I edited could not resist saying, "Put the applicable value into the blah-blah input". Of course, what other value would you put there?

Back then, there were some serious efforts in the field to generate multiple deliverables from a single-source. I have no idea if anyone thinks of that anymore. I've been developing ever since and I haven't worked on a product that even thought they needed a manual. That banking software was written for an IBM mainframe and ran in an emulator so it could work in Windows and it didn't even have the worst user interfaces I've seen since.

Maybe this is a career? I dunno, the author of "Zen and the Art of Motorcycle Maintenance" was a technical writer, he also spent a stint in a mental institution. Maybe it was the software he was documenting?

I can't say. I'd just like to thank the OP for the chance to tell this story.

I see my job as taking in as much information as possible and distilling it into what I think the target reader needs to know. Indeed, I am often asked to document projects just before they are out of the door. Taking ownership over that process, and thinking hard about how I should articulate information, is a delight.

That reader might be someone who is learning a skill (for whom I am writing a "how to"), or a customer who needs to know how to use a software package (for whom I am writing reference and quickstart documentation).

Technical writing has led to some interesting personal stories. An old friend found one of my technical articles while studying for a course; that warmed my heart. As I have written more, I get the occasional email from a student asking about my work.

Happy to answer more questions! (but, honestly, I should blog about this!)

As for getting started with technical writing, setting up a personal blog is a good idea. Document a project you have made in the past, whether it is a website and how you built it, a software library that you made, etc. Or contribute to existing documentation if you have expertise that you can lend (i.e. add a quickstart to a library you use and love, contribute to MDN if you notice something that could be improved).

I’ve participated in report writing as author, editor and reviewer and over the years learned a lot about writing in general. Key for me was understanding the decision that the reader would make as a result of reading the doc, and then ensuring that the doc did in fact present the necessary evidence and ideally some actionable recommendations. The absolute worst thing was when people started writing and just hoped that the answer would somehow emerge (which I admit is sometimes a useful way of getting your thoughts straight), but then just stopped when they ran out of time / budget.

One of my most useful roles as a reviewer, was to conduct a 20% review, near the beginning of the writing, when I would confirm with the authors what sort of message they wanted to get across, and ideally storyboard how they were going to do it. Also, when multiple authors were involved, it was critical to make they sure they used styles etc consistently, and ideally adopted consistent terminology.

I also began to appreciate the importance of an executive summary – the bottom-line-up-front, on a single page or less. If the person who commissioned the work was senior enough, sometimes this was the only bit they would read themselves, leaving the gory detail to minions.

About half of the docs are just direct Markdown, and the other half are in python docstrings, pulled by mkdocs automatically. The "mkdocs serve" dev server works amazingly well for visualizing changes. Highly recommended.

To any technical writers listening :

- Can one make a living from it?

- Typically are you working on a consultant basis, or permanently for a company?

- The job seems like an ideal WFH gig, is this the case?

- Seems to me you will need a 'portfolio' to get work? I'm guessing starting with Open Source projects would be a good way to build up a body of work?

Cheers.

(edit - formatting)

There's clearly a fact-based, no BS writing style that resonates well with HN for example.

Are there tools that help detect such BS in writing?

Hemingway Editor comes to mind, what else?

> Writers mentioned a number of Open Source options, including Joplin, Asciidoctor and GNU groff.

This is a gobsmackingly bizarre list. Joplin is a note-taking app, Asciidoctor is a processing/publishing tool for AsciiDoc, and groff is mostly for publishing CLI docs/man pages.

Most technical writers work in either DITA XML, AsciiDoc, reStructured Text, or Markdown. Aside from using oXygen for XML, you're probably in VSCode or some other open-source plain text editor with a plugin to preview the output.

That content often lives in a git repo, or alongside code in a monorepo. It goes through a publishing tool like the DITA Open Toolkit, AsciiDoctor, Sphinx, a static site generator, etc.

Translation typically involves Gettext/Poedit at some point between a variety of frontends, though scaling that is often how tech writing teams wind up going down the DITA XML rabbit hole.

> Lauren Pritchett: "When I was writing more frequently I liked to write in Atom or something like that in Markdown, then put it in a Markdown-to-HTML converter and plop it into Drupal…"

No. No! This is nonsense. In technical docs you absolutely have to have a publishing pipeline that doesn't include a manual copy-paste step into a CMS order to scale. In technical blogs you're authoring closer to the CMS. This makes zero sense.

> I really enjoyed working with LibreOffice because of the ability to create templates, repeat processes, ebooks and cheat sheets…

There are mature and popular open-source tools to do all of those things in AsciiDoc/rST/Markdown that are easier and better at scale than LibreOffice. Even DITA and the DITA-OT can do most of this, though working with XSLTs sucks.

Notably, Pritchett's background is primarily in marketing content, whitepapers, blogging, and traditional book publishing, not product docs: https://hilgspritch.github.io/work.html

> ... (git and Markdown is) not intuitive, I much prefer Google Docs

If you're doing technical product or dev documentation work, you might be in Google Docs as a bridge with product and marketing, and maybe you legitimately prefer GDocs review tools for editing early drafts of prose.

But if you're writing documentation, then writing docs as code in the same tools and processes ships the docs alongside the implementation. If you can't become competent using git, you're going to struggle mightily in non-marketing tech writing roles.

If you're documenting software, and even if your team isn't writing docs as code, you still need to be able to understand git and fundamental concepts of it well enough to work with the product you're documenting. Your publishing pipeline is probably using a combination of git, CI, and cloud storage, and if your team doesn't have anyone on it who can understand those things then you aren't shipping docs as fast as you could be. Very few non-marketing technical writers make it these days without being competent in git.

-

Also, more generally there's no disclaimer that the moderator of the talk spends a chunk of it talking up a blog that his own consulting company runs and prominently sponsors.