Hacker News Reader

Comment by breckenedge | Hacker News Reader

I graduated with a BA in English with a Technical Writing concentration 15 years ago. I did the job for a few years and, honestly, it sucked. At best, I was treated like an idiot by developers. Developer aloofness seemed much worse back then — they were never wrong. I was always at the end of the software development cycle, so there was never enough time budgeted to do good work. Management couldn’t decide if I was a tester and a writer, so I often had to fill both roles. The rapid nature of software development today is great for users and developers, but lends itself to rapidly expiring documentation. I did the job long enough to teach myself software development. I switched over to being a software dev ten years ago and have never regretted it. Entry level pay as a software dev was better than experienced pay as a technical writer. I have been asked to write documentation, and I’m glad to do it — just not as my primary duty.

View on HN

Twice I’ve seen a tech writer turn into de facto project manager because the real manager was asleep at the wheel.

Without real requirements how can anything ever be done? If nothing is done how do we get paid? If nothing is done and we have no money then what the fuck are you managing? Nearly every secretary or office assistant I’ve worked with has been more useful than the worst managers, and at less than half the salary. I have called this type of manager a glorified secretary before but that’s disrespectful to secretaries.

PHB (Pointy Haired Boss) is a recognized expression in some circles.

https://en.wikipedia.org/wiki/Pointy-haired_Boss

Your comment makes me think that writing primary documentation should always be the job of developers, with time dedicated for the task, and technical writers can do the polishing and categorization that will likely be necessary for it to be published. Being the only one responsible for documentation while not being a developer must be a nightmare.

Yeah in practice there’s just no other way in the places I’ve worked. The problem I’ve encountered still though is getting developers to estimate sufficiently to give that time. Developers massively underestimate (myself included).

The problem is that you are estimating instead of producing and measuring. Just take the time and succeed or fail. Don't estimate it

If you have waterfall, there is usually not enough time to make the product itself, and documentation is much lower priority than that.

If you have agile, in theory all developers are replaceable. In reality, a few have writing skills, but most don't.

I’ve noticed the master software engineers around me tend to have a particular acute sense for naming things, as if after living with and mastering the universe of abstractions around their craft they’ve embraced the linguistic dimension of the work, minimizing cognitive load and aligning execution with intent.

There’s no sense in work cultures I’ve experienceD that engineers should take in documenting their work individually, but having code do what it says on a deep level promotes, ah, grok-ability. But maybe leaving at that leads us inevitably to flawed self-documentation.

Naming tings is so important. Even more so if you know you will not have time the document properly. Typical sign that someone did not take the time to name : utils, shared or misc ...

Seen it so many time in poor quality project. Hardly ever in project that have a high quality bar set.

TLDR: Redesign the product until its description makes sense.

I've done some technical writing. It's hard work. One open source tool I made, I spent more time on the docs than on the actual code.

Press releases, manuals, installation instructions, etc can be great QA/QC tools. If something is hard to communicate, then the subject itself is probably too complicated. Or just badly designed. Go back and simplify.

One stretch, I was also the engineering manager for a handful of products. So I had the juice to compel improvement.

The manuals and installation instructions were, um, challenging. I made the teams reengineer installers, UIs, workflows, whatever until the technical writing made sense. Other benefits included greatly reducing defects and technical support calls.

I also put the QA Test team members in charge of our releases. To great effect. Which I haven't seen any one else do before and since. But that's another story.

I only mention it to acknowledge that most orgs treat writers and testers like crap. Like you experienced. Which is unfortunate, wasteful, and rude.

I’d love to hear more about the QA team managing releases- how did that go?

This was mid to late 90s. I don't know if execution would apply today. But the notions of designing the organization are evergreen.

I riffed on a notion from Ford's idea of quality circles, where engr, mfg, and QA made decisions jointly. And the USA Constitution's notion of balance of powers (trilemma).

My company was engineering driven. Our releases were always late. Way too many defects. QA/Test were demoralized. Sales and marketing weren't even part of the convo.

So I split responsibilities into three roles. Marketing determined feature set and price point. Engineering determined how and schedule. QA/Test controlled the release.

The first release cycle was VERY HARD. People hate change. I was an asshole and burned a lot of goodwill. Thereafter, our releases were always on time, we hit our P&L numbers, reduced our costs (eg tech support burden), and were given ever increasing amount of responsibility.

Later, I expanded the organizational triangle into a star by adding tech support, sales, and writing roles, each with their own responsibilities and authority.

We survived Y2K just fine. But 9/11 crashed our industry and we didn't survive not having customers.

Reply on news.ycombinator.com