I feel we're giving Gordon the benefit of the doubt with this one. I've also written documentation for our own product - on the one hand I know it backwards, on the other hand the documentation is intended for people that don't. It's easy to skate too quickly over content that needs expanding, and focus on bits that the engineer thinks matter but that the users don't.

There has never, ever been writer in the history of the world who wouldn't benefit from a good editor with a fresh set of eyes.

The biggest help with writing a "$SUBJECT for dummies" guide, is finding an actual dummy to help you out (either with writing, or as a guinea pig).

Even if it's just a guide for people who do have the required domain knowledge, the dummy test still applies and is still helpful.

For some of the documentation I write, I have a (nearly) tame English language Rottweiler. He can not only highlight missing information and correct speeling eras but also identifies inconsistent writing style.

I'm not so sure. Of course, we'll only ever have one person's description of it and they're likely to edit anything that they don't want to appear, but nothing in the description says that the problem was missing things which the writing department asked to be filled in. I've known people, and I'm guessing you have too, who could not review something without proposing changes. I wouldn't count out the combination of people trying to justify their jobs and not necessarily being good at them. Most programmers I know would be all too happy to not write documentation, sometimes so much that they don't even though we don't have any writers to do it instead, and the writers probably weren't getting any complaints if the documentation wasn't good.

who could not review something without proposing changes

Back in my second role (Programmer/Analyst at the local college, now a university) we had a boss like that. She insisted on seeing every bit of documentation we produced and always wanted changes on every submission. We eventually told her that she couldn't introduce any new changes once we reached the third draft, only critical errors.

I am fortunate enough that I have never encountered someone who did this severely. Most who I have found need to say something but don't get too unhappy if their changes don't get made. Unfortunately, I know at least one person who had to deal with someone who demanded so many changes that they went to the extent of deliberately including things for the critic to complain about because they would otherwise send round after round of mandatory feedback and force all the team members to stay late into the evening to implement those changes before deadlines. It did not do that person's mental health any good, and of course introducing deliberate confusion or errors into drafts could have had all sorts of other problematic results.

My wife is a tech writer (sometimes for products my team worked on) and has occasionally encountered developers like Gordon. They're too close to the product, don't understand the often silly mistakes customers make, and get very upset when the professional writers want to change their highly technical content into better and more readable English.

Good writers and developers will sit down together with the product, and work out what needs to be done. I doubt if the fault here lay entirely, or even mostly, with the tech pubs team.

Even if we assume all the opinions in the article are wrong, if we agree to accept the facts alleged, the tech writers were not sitting down with the developers to learn the product; they were communicating by written messages volleyed back and forth. Even if the documentation produced by the programmer was complete gibberish, you couldn't make it better without understanding the software, instead getting the kind of thing you would get if you had an LLM write it: clear, well-organized, grammatically correct, and useless. So I still don't think we have enough information to turn the benefit of the doubt to favor them. And if we aren't willing to accept those facts, we might as well make up any story we like because we have no information other than that from the article.

I've written documentation, rough n ready, real Janet and John stuff but accurate and functional with highlighted bits in screengrabs.

They work, 100%, to the point where users come to me and my team for guides which they can rely on to be concise and accurate instead of the corporate ones which only ever focus on success and have absolutely no information on what to do if a step fails (even adding "if this step doesn't work, stop and call support" would be better) which allows users to plough on andake an even biggeress for the helldesk to unpick before throwing it back to us.

Our corporate tech writers often obfuscate stuff and actually remove vital bits because "it's too complex" and we can often see the uptick in support calls for that exact point when their guides are released.

Whilst I don't doubt their ability to create very pretty corporate style guide compliant stuff I do wonder if they've ever actually tried to follow a guide instead of just making them pretty

Changing highly technical content into "more readable English" is a very poor way of handling the issue though. What actually needs to happen is the users need to be at a skill level to understand the technical content in the first place.

If someone isn't skilled enough to understand the technical content, why would they be using a system?

All this way of writing documentation does is increase support requests for missing information.

Agree, but there are times where you will write a document on something and your expectation is that whoever is going to use said document has some basic understanding and you do not need to explain certain parts as anyone who has used or uses said system just "knows".

I do always get someone else to go over my docs incase I have missed off something because I know and I forget not everyone does know, or what makes sense to me is gobbeldygook to everyone else

This!

I've had managers who expected me to condense weeks and even months of training on things like HP EVA, Alpha servers etc into a one pager so they could send any engineer to any job without having to pay for training or expertise

One particular manager (who'd been a warehouse operative until he married a directors daughter and rocketed up the corporate ladder) threatened me with a written warning after my third refusal was less than polite.

I handed in my notice with a polite but to the point explanation and included a quote from an email exchange where that manager had told me that my skills, experience and training were no longer valuable or required then moved on to a far better paid role elsewhere and the company lost their only accredited storage engineer.

I've reviewed documentation for a few systems as a "first time user" - I always see this as the best chance to find out where it doesn't get something across as I have no preconceived ideas about how the system works or is supposed to be used.

I really wish some companies would try something like this with their documentation (right now, I'm thinking of a compiler where the installation instructions don't match the GUI of the IDE into which it is supposed to be installed).

> He instead received a reprimand, and not long after a termination notice.

So he became Gordon Freeman

Half Life icon -->

*HEV Suit charging sounds*

I worked on a large, very popular project. The installations documentation was 30 pages of instructions, then try to start it. It would often barf "ERROR IN $$BOPEN" and not tell you the file name.

For people who had never user it before this was very bad, as they had to start all over again. There were customer reported problems, which the pubs people tried to fix.

Experienced people would not have these problem because they just copied what they did last time, and changed a few names.

I rewrote this in baby steps. Do the following things, check it works. Do the next thing, check it works Do the next thing check it works - it doesn't? - well check the last thing you did.

A developer took this and improved it and we gave it to the pubs department, who made some changes and shipped it.

The response from customers was positive and the number of problems reported on installation went down significantly.

I changed projects. 5 years later I was asked to help a customer and found that the documentation had been "improved" by the new function owner who took out all of the baby steps and so the documentation was now 60 pages of instructions followed by "now try starting it".

I spoke to the new owner who said he thought that all the baby steps were unnecessary. He tested it every release - with the definitions he used the previous time. He had never started from scratch and type every thing in. And yes - there were lots of problems reported by customers.

It felt like a seesaw. Either make instructions clearer, but longer, or make then shorter and less clear.

The person who writes documentation needs to be empathatic - being able to put themselves in the position of someone who knows nothing.

That person simply needs to ensure that what is written works every time for anyone who is using the product for the first time.

That's the rule.

You write documentation for someone who doesn't know the product.

Those who know don't need your doc and won't read it anyway.

In my experience the best way to do that is for the assigned writer to be part of the development team, sitting with the developers and using the product as development proceeds.

Good documentation is like security, it needs to be done with the product, not bolted on afterwards.

You write documentation for someone who doesn't know the product.

No: you need different levels of documentation, even experienced users need documentation - but about things that would mystify a novice user.

Yes: you need good documentation for the new user that assumes that they know zilch; this will let them get it installed & running. I have wanted to try out several packages and given up because I could not get a basic installation to work. Optimisation & customisation happens next.

Also: many programs produce hopeless error & information messages, eg not saying the name of which file is missing, or just the name but not the directory that it is in.

As an investment on the side of my consulting business.

I had a GM who handled the day to day stuff so I wasn't too involved but one thing that drove me nuts was the menu. There were always dumb spelling errors, formatting issues etc. The process was the GM and chef/kitchen manager would name the dishes, do the writeups and pricing etc. and hand them off to our main food vendor who did the menus for free based on how much money we spent with them. What amazed me is that even when we'd keep dishes the same between menu updates sometimes spelling errors would creep in there - as if they are retyping the whole thing from scratch rather than cutting and pasting off the old one.

At first I tried giving them a list of fixes when they'd send the proofs, and while they'd fix some of the issues I'd list somehow NEW ones would pop up in stuff I didn't have any corrections for so they had no reason to touch! I never figured out how that was possible!! So I said "screw it, you guys suck next time I'll do it myself", bought a $100 laminator and some legal sized cardstock to print menus on our office color inkjet (less fancy than theirs, no folds it was just a front and a back on plain white paper) and used LibreOffice Writer on my Linux laptop to prepare it. It probably took me the better part of a day total including a few minor revisions before it went "live". The first time a bit more because I had to figure out how to use all the fancy formatting options to get things exactly how I wanted.

I'm sure 95% of people didn't notice the spelling errors, typos and weird formatting issues on the old menu, but once I took over we probably had the English teachers and OCD types nailed down lol

I'll be honest, a bunch of typoes in your menu would have given me a bad impression of the place and would likely have turned me off coming back. If you can't even spell things properly, what else is wrong there?

Totally agree. the little things matter, especially if it's one of the first things every customer sees and looks at quite closely.

So maybe the chef can cook, but who's got their finger on the day-to-day running of the place? That shabby menu might be indicative of other corner-cutting behind the scenes - Who can tell?

You were 100% right to prioritise fixing that.

I take your point but I think we need to be a little bit sympathetic, especially if the menu is written in a language which is not the restaurant owner's first....

I've had delicious 'Giant Squit' in Greece.

But hopefully you were reading the - novel - English translation under a description in perfect Greek.

Admittedly, hard for you (well, me*, you may speak the language like a native) to tell, but I have passed an Italian menu over to a friendly native on the same table to check...

* It is all Greek to me!**

** Could I have resisted that one? Never!

@Sam not the Viking

And I have had God knows how many gallons of Stella Artosi in my local!!

Ishy

"If you can't even spell things properly, what else is wrong there?"

This exactly. There seems to be a school of thought in the UK that correct spelling isn't important as long as the reader manages to figure out what is meant.

At the end of the school term before the summer break this year, a number of "Public Exhortation" type posters, presumably generated by the local primary school pupils, appeared on various bits of street furniture around the village.

These included such orders as :

"Please do not liter"

"Pick up your rubish and help the enviorment"

"Don't drop your sigaret butts on the floor"

Laudable though the intention behind these posters may be, my immediate thoughts were "What does this say about the quality of education these children are receiving and what does it do to the reputation of the school?".

As a general rule, if you want to tell people what to do, make sure you spell it right otherwise they're perfectly justified if they ignore you, claiming "What do they know, they can't even spell"

I used to wish I had the spare cash to print out stickers with the word "find" on them and place those on all of the parking signs when Cribbs Causeway Mall opened. The signs that, to this day, exhort everyone to remember which row they parked in, in order to "relocate"* their cars.

Especially as, over the years, people have had their cars relocated and didn't seem very pleased about that.

* I blame this on the tendency of certain people who insist that using long fancy words badly, instead of short, pithy and correct ones, make them sound clever and posh. Sadly, they are not unique** in this misapprehension. A shame, as the vernacular is chock full of subtleties they might use, if only they'd bother.

** Interpret this correctly or in the, shudder, commonplace erroneous fashion, it is accurate either way.

The number of places, takeaways, cafes, restaurants etc that have absolute howling bad menus, it's jarring to me and the mistakes leap off the page immediately

I had the opposite issue once. First supervisor used to insist on writing all the documentation. He was a chemistry degree holder and wrote things at a deliberately high level as a way to show off / suck up to our group director (Phd holding chemist). The level of arse-kissing was a little pathetic and OTT, he even used to buy the group director a box of chocolates and a card for his birthday every year...

The production documentation he wrote was hopeless. Over three quarters of the production tech team I worked in had English as a second language and weren't all particularly fluent, yet our process required meticulous documentation.

A new supervisor started with the old one being punted off into "R&D" to get him out of the way, I guess it was easier than trying to sack him for being useless.

About a year later I was found to have some good aptitude for writing the SOPs and got tasked with rewriting everything in a way that everyone could understand - so at the level of about a six or seven year olds vocabulary. Myself and my bench desktop PC got tucked into a storeroom as a "skunkworks", I spent about six months going through the SOPs and rewriting them, then reviewing with the supervisor or the other production techs.

The only blocker was the former supervisor was still an approver in our QMS for all documentation, and took it very, very personally that I'd rewritten all "his" documentation from literally top to bottom. After a lot of back and forth for two months or so over who's job it was to sign the documents off I seem to recall the end result was him being removed from that approval chain by our group director!

I wrote the 'Standard Procedures' for our newly-formed company in order for the 'workers' to achieve consistent results. Short lists, descriptive bullet-points for stage-completion as the item moved through production. I tried to keep each procedure within a single page of A4; the whole set relevant to a product easily contained within a slim folder.

After being taken over, the Head Office QA machine took over and turned the procedures into multi-page documents, each page topped-and-tailed with multiple QA document-approval levels, prepared-by, approved-by, checked-by, signed-off by, all dated, company logo, Head-Office logo and address..... etc. etc. The working-information was verbosely expanded and moved deep within the document and the whole series compiled into a large binder.

This binder was so unwieldy, it was largely unread. But gosh, QA updated it often in order to prove their worth.

Had a menu for a few years with a (regularly updated) "Desert" section!

I appreciate dry humour.

For some strange reason, when I write User documentation, complete with a plenitude of immaculately presented screen dumps that illustrate, via the medium of chromatic shadings, the methods the algorithm uses to differentiate the various and assorted subtleties between the meanings of the data being presented, in order to increase the probability of a successful conclusion to the day's proceedings, there are those who bemoan not so much the quality but the quantity of the, as they may refer to it, verbiage, in the, so I am informed, excessively brobdingnagian printed matter. "We wish a pamphlet, not a tome" the cry goes out.

Next day, a thinner version is handed back. I'll check that troubleshooting steps were pasted to a.n.other place, with a crossref, and hand it back, glad to be shot of the thing.