> The best software companies have a dedicated team of technical writers and their own chain of command and comparable salaries to coders
Can you provide some examples? I've never seen a technical writer job post on this site as an individual post, and I don't see a single mention of documentation work in the recent Who's Hiring post.
Apple and Cisco are two examples of companies with large, well-organized technical documentation teams. I've worked on both teams. There are certainly many other examples.
I've also worked for a few startups on setting up their technical documentation processes.
My career in software started January 1, 1988 at Apple. Roughly 1/3 of my career has been as a technical writer, and 2/3 as a programmer. The two disciplines require comparable levels of knowledge and technical skills, but programming generally gets much better funding and other support.
There are several reasons for that. The most obvious is that you can't ship a software product without some programming, but you can ship one without any technical writing. It's generally a bad idea, but it's possible.
Another reason is that technical documentation is in almost all cases a pure cost center. You don't make money from your technical docs. Worse, you can always make docs better with more effort, so there's no theoretical ceiling on its cost. How expensive are docs? Well, how much have you got?
Yet another reason that docs get short shrift is that smart people tend to assume that they can write. They are often mistaken. Among professional tech writers and editors, "engineering documentation" is a pejorative phrase. Nobody thinks that they can write good software with no experience and no training, but many otherwise intelligent people make exactly that assumption about tech docs.
Also, it must be said that technical documentation is probably the least cool job in software, even less cool than compatibility testing. Nobody ever called a tech writer a "rock star" (although I can think of a couple that probably qualify).
I haven't seen a lot of hiring posts for tech writers on HN, either, but that doesn't surprise me. HN is sort of startup-oriented, and it usually takes startups a while to realize that they need professional tech writers. It happens when someone realizes that they're spending too much supporting customers and partners because they're not spending enough on docs. That's when they go shopping around for someone to help them fix that problem.
I've been that guy before, and I also know a good recruiter who specializes in that, in case anyone needs a contact.
> Among professional tech writers and editors, "engineering documentation" is a pejorative phrase.
Not here. It's documentation written by and for a different audience, and it's valuable. As a professional technical writer and editor, I vastly prefer it over having engineers who won't write anything.
Tech writer value comes from adapting engineering docs for other audiences and use cases: identifying what context needs to be there (or doesn't), providing the value prop, demonstrating real-world workflows, presenting it in a broader narrative of productive usage, and finding ways to make it all confirmable and maintainable over time.
But we aren't (often) engineers, and we need those engineer-written docs as a starting point for our own understanding. I'd avoid ever being pejorative about that. The problem's usually with a culture — or leadership — that believes engineer-written docs are enough for non-engineering users, and that all any tech writer should do is proofread and publish them.
Your point is well taken. Consider my remark a bit of hyperbole--though I've definitely been in more than one conversation in which tech docs professionals described something as "engineering docs" with the clear meaning that it fell below some acceptable standard.
I'm a one-man operation, and I want to have great docs, so much so that I even spend lots of time on docs in my free time project. [1]
Besides "know your audience," "understand your purpose," "proofread," and "test your docs," what advice can you give a programmer to be a great technical writer?
Being a great tech writer is pretty ambitious. Maybe start with wanting to be a competent one.
The way I learned was by being a junior writer at Apple surrounded by much better writers and professional editors. They assigned me what they thought I could do. They reviewed my work and taught me to make it better. The editors were generous enough to not only correct my mistakes but teach me why they were mistakes.
Not everyone has that opportunity, obviously.
Write a lot. Seek good feedback.
Good feedback tells you whether the reader learned what you meant to teach. It tells you how hard it was for the reader to learn it, and where the text was confusing or hard to follow or just plain hard to read.
The best-quality reviews I've ever gotten were from professional technical editors--no surprise, since that's their whole job! Still, you can do pretty well if you can find a smart, literate person who is comfortable telling you clearly what works and what doesn't in your work. What you need to know is whether your work engages the reader, is easy to read, is clear, and conveys the knowledge you intend.
You'll have to write and write and write. Write a draft and get it reviewed. Fix its weaknesses and get it reviewed again. Repeat until you just can't make it any clearer, simpler, and more successful.
Write about different subjects, then take those drafts through the review process.
Review your own writing, but not too many times, and leave enough time between readings. If you try to review too soon after you've written a draft, or too many times, then you'll miss a lot of mistakes because you'll see what you expect to see instead of what's actually on the page. The right limits might be different for different people; for me it's best to wait at least a day after I've written something or previously reviewed it.
Oh, and I should add: print your drafts and mark them up with a red pen. It's a different experience from editing and correcting text on a screen, and I find it helpful in ways that differ from online editing. If you want to try it then you might like to consult this cheat sheet:
Read about writing. The Elements of Style is dated, but still good. The same goes for Words Into Type. The Chicago Manual of Style is a huge tome, but is a standard for good reason. Every Page is Page One is helpful, especially for writing documentation that winds up on the web.
Publications departments generally supplement references like these with in-house style guides. You might see if you can get your hands on one or two of these. Their main purpose is generally to teach new writers how to sound like the particular pubs department, but they also encode stylistic decisions that are intended to keep the text clear and accessible. You might not want to slavishly imitate any specific house style, but reading a few guides and thinking about what they're trying to accomplish can help you think critically about your work and develop your own style.
If you can think of technical publications that you admire, see if you can find the style guide that governs them. Read it and think about why they're giving the advice they do. Cherry pick the good thinking and apply it to your work.
Take a look at Diátaxis, which provides a nice structured way to think about the different kinds of tech writing and their different purposes.
Hi! I've been a technical writer at several startups, all B2B SaaS, mostly mid-stage 200-400 employee companies. In two of them, I was the first writer hired.
I'm not surprised that HN Who's Hiring posts don't target us, because I don't feel like tech writers are really the audience here. Smaller startups might benefit from a dedicated tech writer, but the resources are harder to justify. Larger companies are either contracting maintenance of existing sets or already have established teams.
So it's often that sweet spot combo of a funding round, new product launches, and eng/R&D scale-up or M&A where a startup decides that they need one or more dedicated technical writers to clean up and reorganize existing content and make maintenance more scalable. It's a specific, fleeting moment of hiring the first 1-to-5 writers, after which new writer positions fill pretty quickly via referrals, intern-to-hire, direct recruitment, or internal transfers. (I've been hired though three of those.)
This site isn't representative of all software jobs, or all software companies by any means.
That said I've also very rarely seen a posting for this. I've worked at a few companies that had 1-3 people doing it full time. But in every case I can think of they were exceptionally competent individuals who had started off in either support or engineering and gradually took it on as an explicit role because they were willing to do it and once they were the value was obvious.
Quote was shared to me by the president of a defense contractor where I worked as a contractor on a project to surface (excuse the pun) that SGML document.
In general, I’d like to see more companies treating documentation as a first class product, with dedicated technical resources and product management team. I wrote about that in a post presenting what I call the “Docs Hierarchy of Needs”: https://passo.uno/docs-hierarchy-of-needs/
Potentially interesting that the E-Myth series of books on entrepreneurship essentially asserts that the company itself is documentation because processes that can be readily and reliably communicated to employees are at the core of consistent value generating operations.
Putting animated GIFs into your documentation or blog articles, negatively impacts legibility. The constant movement diverts attention and makes people skip that section so they can just scroll the annoyance out of view. If you MUST include animated guidance for whatever reason, use videos that have playback controls and are paused by default.
Seeing this in an article on how to improve documentation makes me question any message you might try to get across.
Thank you for your opinion. We actually don't use GIFs in our documentation and are limiting the use of screenshots and similar visual assets as it can go stale easily. We do rely on videos where necessary.
There are ways of adding reproduction controls to animated GIFs. Animations have their place and purpose depending on the type of documentation, especially when you want to illustrate some complex steps.
When is an animated GIF showing a series of complex steps better than a video of the same? The video has the advantage of offering things like audio, higher quality playback, the ability to be downloaded locally and played in VLC (where you can do things like zoom in or slow it down), etc. Maybe not all of those things are needed in every case, but even then video will get the job done just as well as a GIF and provide consistency with any instance where you do end up needing video's features.
I for one am a text person, and for me video is death - the end of my attention. Very very few videos use my time as effectively as I can when I am setting the pace and maybe deciding when and how to skip around.
I agree that if something can be explained in text I'd much prefer it over a video, but if you need (or expect some people will need) to see a video a GIF seems like the weaker option for how to present that.
If you're given a task that is not obvious and requires pauses for familiarization at several steps, isn't it easier to deal with text+illustrations than with video ?
And animated gif is the same as an animated video sans audio.
Gifs can be used to not need a ply button to visually demonstrate something but the oerson making it must have some story boarding and visual communication skills.
Gifs are just one tool in the toolkit. Expecting anything to be silver bullet or disqualifying anything that isn’t a silver bullet sets backs documentation much more.
You always want a play button. The idea that the video is so important that people should be watching it before they discover what page they are seeing or read any contextualizing text is absurd.
If you don't have a play button, nobody will watch the full video. This is ok for doomscrolling social media, but I am quite sure it's not ok for your use-case.
I generally agree, but there are valid cases where play buttons aren’t needed for an animation in every case as you’re saying.
We literally have seconds if that to communicate enough for the user to decide their needs are represented in the screen, to stick around and read and click some more.
Let’s look at gifs and videos as something much simpler - an animation of frames that either auto plays or not.
Having a short, looping, auto playing animation showing a showing a feature or overview with a progress bar can be a positive implementation of negative doom scrolling patterns. Have seen this implemented very well in documentation in addition to text and videos.
The user can pay attention to a looping animation quite well because they’re used to it, including waiting for the loop to restart like they’re already used to. This in turn can accidentally feed some reinforcement learning mechanisms, especially where the primacy effect is involved. Watch the short loop a few times before diving into the full video.
Another use that work well is automated and timed flash cards where clicking, no JavaScript or being offline can be a consideration. Good for hands free, or limited hand use availability. Yes it can be scripted too.
Animations can also be useful within a carousel on a hero component where the resistance to press play on a video might be occurring.
Gifs and their ability to animate frames is just a capability, how we’ve seen them used should not define the limits of what they’re good for.
Inertia maybe? A web page peppered with video controls and blocks seems busy and distracting to me. It feels like heaviness, bloat and overhead (even if technically it isn't). A couple of GIF animations showing simple actions works for me. So it may be more subjective than objective?
For steps that take less than 10 seconds, I’m not sure a video would prove superior; GIFs are easier to produce and easier to publish. Then again, I’m also pro-videos.
Documentation has always been part of the product.
Documentation has always been part of the coding, not an afterthought, not an optional thing, not a second-class citizen. This is how I was taught in university. I'm still baffled to see how many developers believe the key to professional success is writing a lot of computer code, as fast and as efficiently as possible. Then you go to their GitHub repos for their personal projects and they're completely unusable because you don't even get installation instructions. Best case scenario you will get an auto-install script that works on Debian 9 and has been unmaintained for years, but at least you can read what it's doing and adapt it to your distribution of choice.
I had a classmate who got hit with this issue from the opposite direction. In our first semester CS course, 70% of our grade was based on our documentation. My classmate wrote beautiful, comprehensive documentation of the solution program to each solution set. They also didn't write a single line of code the entire semester, passing the class entirely on the strength of how they documented software that wouldn't even compile.
By the time that they reached the more advanced courses, where producing a working program was a requirement, they were so far behind that continuing in the program was hopeless (e.g. being asked to write a database when they'd never even attempted "Hello, World").
If the department counsellors had been on the ball, my classmate would have made an amazing technical writer, but I believe they wound up switching to electrical engineering.
> I'm still baffled to see how many developers believe the key to professional success is writing a lot of computer code, as fast and as efficiently as possible.
I wonder if developers tend to believe this, or if leadership incentivizes it, either explicitly[1] or implicitly.
> Rezaei tried to rally the troops, telling engineers to focus on shipping code as quickly as possible:
> "So if you ask what should I do now: do good engineering work. Write code. Fix bugs, keep the site up. I know the criteria for being at Twitter is that. It’s not working on a fancy project for Elon. The good culture change is, it’s shipping and delivering. I encourage you to rotate more on coding and shipping, and less on documentation, planning, strategy etc. If you want to be in a “special” group this week, code and ship 5x as [much as] before. ..."
Probably an unpopular opinion, but if you want rock solid documentation, switch to waterfall.
I just dont think its possible with agile. It's always lacking. There are degrees of quality, sure. Aspire for good documentation. But there are too many moving parts by too many hands and there are diminishing returns on documentation efforts.
Also consider that every piece of documentation you write adds onto the documentation burden. The more you document, or the more specificity you give in documentation, the harder it is to have accurate docs. Auto-generating stuff gets around this but is usually of limited value.
Of course it is possible with agile, it "just" needs to be properly prioritized. And that also means, in good Agile fashion, that documentation skills needs to be represented in the team. If you don't prioritize documentation and do not value technical writing skills, it doesn't matter whether if you use waterfall or agile processes, you will still end up with sub-par documentation.
Also, what kind of documentation? High-level design documentation? Low-level code documentation? Code structure reading guides? End-user manuals? Elevator-style sales flyers?
As an exercise, change your statement from ”If you want rock solid documentation, switch to waterfall” to,” ”If you want rock solid tests, switch to waterfall.”
They have all the same organizational forces acting upon them. You don’t need all the tests to “ship a feature.” So some people can certainly skip some or all of them.
Switching to a highly iterative process neither worsens nor improves the quality/completeness of your test suite. Rapid evolution of features places pressure on keeping test suites current.
Iterative processes with good tests in place exist only because entire engineering departments have “gotten religion” about their value, and product managers have come to accept that it’s important to invest in tests. If they didn’t, they’d give engineers too much work in too little time to write tests.
And so on and so forth. Great tests and entire infrastructures around tests only happen when an entire organization buys into their value even if everyone knows you can get away with writing a negligible amount of test coverage and still ship a feature.
I submit it’s the same thing with documentation. It’s not a process problem, it’s an “embracing their value” problem. If you’re in a culture where tech writers are not considered as valuable as engineers, you will have crappy documentation no matter what you do to the process.
> I just dont think its possible with agile. It's always lacking.
I don't think it has anything to do with waterfall vs. agile. If, in agile, you declare that no story is ever complete until the documentation is complete (same as it's not complete until it passes testing), then boom, it works.
Documentation has nothing to do with methodology. All it has to do with is whether the manager/lead signing off on completion requires documentation to be considered part of that, and enforces that.
It's nothing about "degrees of quality" or "aspiring". Either it's enforced policy or it isn't.
I've held that view before, but in practice adding friction to review and deployment doesn't accomplish much other than frustrating engineers.
Aside from that, the code review process is also too late. A better spot would be during the design process, then updated alongside the implementation to match. By the time you get to code review, the docs for the relevant code should naturally already be written, without needing to set and enforce a docs requirement.
The best software companies have a dedicated team of technical writers and their own chain of command and comparable salaries to coders.