Get started with technical writing

https://opensource.net/get-started-with-technical-writing/

159 42 3 years ago

Way back when I was a young lad, a hiring manager found me because I had an English major and hired me to help maintain a manual for a small bank system. I did a hell of a job but the job was hell. My manager actually put a co-worker in a choke hold at a customer site while they were transitioning their bank to the system. This was way back when, and I put way to much effort into my work; they were dragged along and the whole thing was thankless.

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.

tomcam• 3 years ago

Am I especially good at writing? Not in my opinion.

You’re an excellent writer.

roydivision2• 3 years ago

Agreed, you craft a good sentence.

wmidwestranger4• 3 years ago

Thank you, sir. I'll keep this in mind when I doubt myself. Much appreciated.

greenie_beans• 3 years ago

My manager actually put a co-worker in a choke hold at a customer site while they were transitioning their bank to the system.

wait what? gotta hear the full story

wmidwestranger4• 3 years ago

Yeah, he was their lead of training. He had worked in small to medium banks and then tried to set up a consulting business but that's hard enough without having the temperament that leads to putting a co-worker in a choke hold. I _can_ imagine worst managers but he was pretty tough for me, since I didn't want to waste my time doing poor work when I could be doing good work.

So this system was about as user-friendly as you can imagine any 30+ year old bank management software. They would sent a team to on-board new banks. The team would usually have this manager or his subordinate, a networking guy, senior support staff. This manager happened to be very hard of hearing but was unwilling to get a hearing aid or sort that out. So him and the others were out drinking after the previous day was over and he was trying to hit on a lady that clearly wasn't interested but he couldn't hear her clearly nor read her lips well enough to take a clue. The next day, in the bank, the networking guy who had been there forever and was friends with the President said something about how he couldn't take a hint and my manager lost his cool, put him in a headlock in the middle of the bank, and probably came to his senses a few minutes later. He was sent back early and the story returned with the rest of the team. This was a small / medium business and he was relieved of joining the on-boarding crews but kept his job.

Lots of mixed feelings about that place. While it paid terribly, it is the only place I've worked in 20 years where there was an honest to god retirement party for one of their QA staff.

starkparker• 3 years ago

What tools do you use for your writing?
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.

spondylosaurus• 3 years ago

Very few non-marketing technical writers make it these days without being competent in git.

At least in the software industry, agreed. Not only is it reasonable to expect a TW at an dev-heavy org to familiarize themselves with devs' tools, but it's also damn near impossible to find a good tool for software docs unless you're running your own static site generator.

Every premium CMS tool on the market has some kind of dealbreaking fatal flaw... among them their average price, because good luck getting any budget for documentation :P

MilStdJunkie• 3 years ago

Introducing Asciidoc to a aerospace team, I was lucky if anyone in the room even knew what git was, let alone how to use it.

Every publication system carries with it the paradigm of the industry it's born from, and so-called "docs-as-code" is no different. I still believe that Asciidoc+Version Control+Build Engine of Choice is absolutely the way to pump out complex documentation, but my belief in that fact is probably shaped by the fact I'm at least half programmer myself.

When you have an org that doesn't know what merges do, and who absolutely, positively will not review a draft that's not dead tree, the "docs-as-code" approach runs into some real speedbumps, because you have to get all that SME crayon scribble back into the system somehow. It's honestly a problem I still haven't solved yet, in spite of multiple years of effort, to my shame. I just can't see how reviewing a PR is hard, exactly. Like, what part? The part where you see the changes? I dunno.

Of course your big ERP vendors will have all the answers here, which is always "Use More Brand X ERP". The secret move is that ERPs come with VP level - and above!! - backing, unlike your Publication System Initiative, which has the backing of maybe a second-tier manager, some PMs, and some burnt out CMS admins.

shrubble• 3 years ago

Just a note to point out that groff can use different macro sets such as ms or mom and produces decent PDF/PS output (from my limited testing).

3x35r22m4u• 3 years ago

The first time I had contact with a book from O'Reilly was some point in 1997 with their "Running Linux".

One of the things that I still reckon is the small section describing the book pipeline, the editor used by the author, typesetting and DTP. IIRC they used Emacs, LaTeX and Quark Xpress. I loved that tidbit.

blindriver• 3 years ago

The two most thankless jobs in tech are Project Manager (ie, the person who keeps track of project progress) and Tech writer. Both have been continuously blown off by engineers since the dawn of my career, 30 years ago. Both are powerless to hold engineers accountable and especially Tech Writers don't get any credit even though most customers rely on them completely. Engineers think they're too good and too busy to do technical writing for documentation, but then blow off technical writers who want to do the work for them and just need a few hours to understand features, etc.

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.

rapnie• 3 years ago

It helps when tech writer is (semi)embedded with the agile team. I worked at a company where the writer would rotate between 3 teams, join daily standups and sit side-by-side with devs in kind of pair programming/docs sessions. That worked very well. It can also be used to tackle 'docs debt' when issues on the tracker are explicitly dedicated to transfer fuzzy-knowledge-in-experts-head into docs, in order to catch up. If you don't plan docs efforts well in sprints, you get devs thinking "Oh no, annoying tech writer is coming to my desk to distract me, and I'm so busy". Foster a culture that includes attention to quality docs.

SadCordDrone• 3 years ago

I don't really think technical writers are held in same contempt as project managers. They don't make life hell for engineers without knowing shit. At least they understand the tech more than project manager who just tries to move tickets and create meaningless metrics.

On the other hand, why would you hire English majors without any technical background for technical writing? At least you should give them some training before letting them work.

julian_t• 3 years ago

Years ago Wrox Press got me to come in and give a basic Java programming course to the tech editors who were going to work on a series of Java books. They were mainly English and history grads, and the head man wanted them to have some idea of what they were working with. It definitely made the whole writing process easier from the pov of the author.

remoquete2• 3 years ago

No engineer values tech writers

Not in my experience. Many engineers value tech writers — and reap many benefits from this relationship.

verletx64• 3 years ago

Technical writing is a difficult skill to be proficient at, so I think dedicated technical writers are needed in many companies. I’ve also not really seen writers be “blown off”. More often I see an absence entirely of writers, but that’s usually more to do with budgeting more than anything else. Where I’ve had writers working with me, we’re generally thankful to have someone proficient at it handling things.

With that said, I don’t really see the English major idea panning out well, just as bootstrapping a project with a bunch of CS grads probably wouldn’t. The study and analysis of literature is tangentially connected with technical writing for commercial purposes.

They can, of course, become good technical writers over time, but a huge component of what writers bring is an understanding of the audience. It goes beyond being able to write well, and academic writing is different from commercial writing.

JHonaker• 3 years ago

We actually have an internship program with English graduate students to be tech writers for our data science groups. They're wonderful, and I will sing their praises anywhere I can. Having people whose primary skill is knowing how to write is extremely undervalued in Corporate America. If you're only using technical writers to help with documentation, you're doing it wrong.

nicbou• 3 years ago

I write documentation about German bureaucracy for a living, and I’ve even never received so much praise in my life. It’s heartwarming.

Developers also appreciate useful posts and good documentation. I often leave comments or send emails to praise useful posts. We come to recognise domains with good answers in the search results.

However this might not translate to appreciation by the business. I can’t deny that.

bryanrasmussen• 3 years ago

Companies do not as a general rule value tech writers. They seldom hire them.

Tech writers get paid less than other profiles, so why would you do it if they company did hire them.

PMs do not set time aside for programmers to do tech writing, nor do they set time aside for them to talk to tech writers if tech writers are hired. Thus programmers are taught to blow off tech writers in favor of making their ticket move through the scrum board quicker. n

ska• 3 years ago

One scenario I've seen this work differently in is a regulated market where the technical documentation is part of submission etc. - so if it's not right, you don't have a product.

In this case they likely work for the RA/QA team, and likely can hold engineers accountable for some things, and the engineering team will definitely feel heat from above if they are holding up or derailing the documentation and labelling efforts.

In this scenario I've seen many engineers genuinely help and value the tech writers - even if only out of fear of becoming responsible for the docs.

wmidwestranger4• 3 years ago

One of the most hilarious ironies about technical writing is that the writer has to do so much more reasoning about the system as an interconnected and operating system so they can describe how the user interacts with that system. I think you're correct about how PMs and technical writers are regarded and, as sad as it is, the truth is that engineers are usually rewarded through moving tickets from Not Started to Finished instead of building working and reasonable systems. If "finishing" tickets is where the money is, taking the time to reason about how any ticket fits into a coherent and correct system is an expensive process. More often than not, people are not successful because their projects are so good but that the project was good enough, long enough, and they moved on to greener pastures before the mistakes caught up with the system.

RickJWagner• 3 years ago

Tech writers are like the hub in a team-wheel. What they learn, they amplify and share. It's the greatest ROI of all the team positions.

Hats off to our under-appreciated friends, the writers.

P.S. I once worked at a place where many of the Engineering managers started out in Tech Writing. It made perfect sense, because the writers had to know everything to document it. A good Engineer will master one tiny sliver, plus may have knowledge of a few adjacent parts. The Writer hears/sees/writes it all.

roydivision2• 3 years ago

I've been mulling over the idea of transitioning from Sysadmin/DevOps into technical writing for a while now.

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)

dieselgate• 3 years ago

I worked a year as a contract technical writer between undergrad engineering and starting a dev job. It was mainly a lot of manufacturing process documentation and process time studies.

Technical writing can vary quite a lot.

nickfromseattle• 3 years ago

I worked with an engineer that transitioned into technical writing. They worked in-house as an FTE and owned the company's knowledge base, and had no prior experience with our industry before his role.

It seemed like a lot of:

- Developing and enforcing a style guide

- Updating and creating new docs

- Communicating with PM / dev / support for prioritization & accuracy

B2B companies with enterprise customers need good docs to scale support and I'd imagine technical writing for open source projects + a technical CV should be enough to help you land a job.

nprateem3• 3 years ago

AI will destroy tech writers.

mikeravkine• 3 years ago

Where do I get one of these tech writing destroying AIs that will both understand how to use my product and produce clear, concise guides for doing so without burdening the existing team?

dv-tw3• 3 years ago

To answer your questions:

- Yes, you can absolutely make a living from it. Salaries do vary greatly, though, across location and industry. I've more than doubled my own salary in 5 years moving between roles. API tech writing or developer docs is one specific area where you can make a pretty high salary. Your previous experience could certainly help you here.

- I have always worked in permanent roles, but there are a lot of consulting opportunities out there if that's your preference.

- I have been working from home since 2020. I enjoy it because I need the focus and quiet time to complete projects.

- Yes, for my last job search, most companies wanted a portfolio. Open source is a great way to start. You could also check out the Google Season of Docs program. Do you have any written documentation from your previous roles, such as process docs, etc.?

This is my second career, and I truly love the solid mix of technical, helping other users, and working with language. Best of luck!

sarupbanskota2• 3 years ago

I was hoping to discover tools, free or paid, that specifically help with editing copy aimed at a technical audience.

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?

remoquete2• 3 years ago

The Vale linter, though it requires some initial decisions. https://passo.uno/posts/first-steps-with-the-vale-prose-lint...

sarupbanskota2• 3 years ago

So cool. Looks like the proselint site is down. For anyone else who wanted to read the approach - https://github.com/amperser/proselint/blob/b5b7536bec5fd461e...

zerojames2• 3 years ago

I am a technical writer and have been for ~4 years. I love the work that I do. I got started because I loved coding and writing.

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).

zerojames2• 3 years ago

I have written a post about this: https://jamesg.blog/2023/11/27/technical-writing/

KineticLensman• 3 years ago

Something not really discussed here is technical report writing, something I’ve done a lot of while working on govt-funded research tasks, usually in the world of simulation-based training. The aim isn’t to write documentation or user-manuals, but to communicate findings from tech research / de-risking projects to decision makers and other stakeholders, in my case often exploring the question “is this technology ready to use in this context, and if so, what should we do next”. The findings themselves are often generated by tech staff, sometimes involving academics, based on building prototypes and then deploying them in a semi-realistic context with some tame users.

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.

linsomniac• 3 years ago

Over the last couple weeks I wrote some extensive documentation for an Open Source project, and I ended up using mkdocs published to github pages when I commit, via github-actions. That's been a really spectacular experience.

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.

dv-tw3• 3 years ago

I love working with mkdocs. I just used it for the first time this year, and I found it to be very straightforward. It allows for just the right amount of customization for my needs.

Get started with technical writing

Related Stories