Live data from Hacker News

Docs for Developers: An Engineer’s Field Guide to Technical Writing

apress.com

11–20 of 52 posts

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#11
post #10

Earlier quoted context omitted.

The flip side of this (from my ~8 years of experience as a technical writer (TW)) is that once you hire a TW the natural tendency is for engineers to relinquish all responsibility of docs. The happy medium IMO is to put some responsibility for docs in the engineering ladder (not as a nice-to-have for promotion but a legit expectation) and to likewise have an expectation in the TW ladder that they cannot do all the do…

Serious question, if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it? You wouldn't expect TWs to dabble in the prod codebase.

> Serious question, if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it?

Software engineers are the SMEs whose knowledge TWs are trying to crystallize into documentation; them being disengaged from the documentation effort is the same problem as business SMEs being disengaged from the software development process. And, for much technical documentation, developers of the software are also part of the target audience, as one function the documentation serves is knowledge preservation.

Docs need tech SME and target audience engagement for the same reason software needs business SME and user community engagement.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#12
post #9

Not very much off-topic, I wish someone makes https://docusaurus.io as a service.

Docusaurus is a typical node-based SSG, you can easily run it on Netlify, Vercel, or other similar sites. They even have docs for how to do it: https://docusaurus.io/docs/deployment#deploying-to-netlify

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#13
post #10

Earlier quoted context omitted.

The flip side of this (from my ~8 years of experience as a technical writer (TW)) is that once you hire a TW the natural tendency is for engineers to relinquish all responsibility of docs. The happy medium IMO is to put some responsibility for docs in the engineering ladder (not as a nice-to-have for promotion but a legit expectation) and to likewise have an expectation in the TW ladder that they cannot do all the do…

Serious question, if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it? You wouldn't expect TWs to dabble in the prod codebase.

> You wouldn't expect TWs to dabble in the prod codebase.

I actually think you should expect TWs to dabble in the prod codebase. At least for TWs writing docs for developer products. To write the Chrome DevTools and Lighthouse docs I frequently looked at the implementation to figure out how things actually worked. From time to time someone would file an issue on the docs and we would realize it's really just a flaw in the product that can be relatively easily fixed. I couldn't get engineers to prioritize the work but if I put in a fix myself someone would review/approve it. Rather than jump through hoops to update the docs to reflect this quirk, it was often faster to just put in a fix in the product itself.

> if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it

As mentioned in the last paragraph, a difference between our viewpoints is that I do expect TWs to dabble in the codebase, so perhaps it's not a stretch to imagine how your business might improve if you also work in reverse (engineers dabbling in docs). In practice, the real "synergy" happens when engineers get into the doc creation process early and often. For example, a writer might create a very rough draft of a guide and ask the engineer to review for technical accuracy only. (Edit: as dragonwriter mentioned, it's often much more efficient for TWs to go to engineers for technical information, rather than deciphering it out of code, PRDs, etc.)). Or, have engineers write the very rough draft themselves and have the TW turn it into a polished document. Another approach is when the engineer is very motivated to improve their writing, and they take on writing a doc, and the TW works with them step-by-step to polish it into a usable doc. My hunch is that for any given org, you'll only have a minority of engineers who want to improve their writing like this, but when it happens it should be prioritized/rewarded/encouraged. One area where it might make sense for engineers to mostly own the docs is API references. There should be an expectation that any changes to the API should also require a doc update. Another useful expectation would be to have engineers review docs after making a change to the product and make sure the required documentation update is at least logged as an issue somewhere. Over time you tend to see engineers engaging with TWs more substantially ("I was reviewing the doc for change X and noticed that the overall organization of the guide seems a bit off...").

I'm not arguing that engineers should take on all the docs work themselves, just as I'm not arguing that TWs should take on all major software development. But from my experience there's a lot of benefit to having each role systematically take on a bit of ownership of each other's domain.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#14
post #3

I do think clear writing is an indication of clear thinking, which leads to clear programming. However, technical writing is a real job with real work involved. To make developers write all the documentation is the same management mentality some places have about hiring “full-stack engineers.” The places I’ve worked at with truly excellent documentation had full-time technical writers that collaborated with engineers…

The flip side of this (from my ~8 years of experience as a technical writer (TW)) is that once you hire a TW the natural tendency is for engineers to relinquish all responsibility of docs. The happy medium IMO is to put some responsibility for docs in the engineering ladder (not as a nice-to-have for promotion but a legit expectation) and to likewise have an expectation in the TW ladder that they cannot do all the do…

Interestingly, I think the exact same thing can happen with QA work. One of our QAs told me about a past dev that believed he was off the hook for QAing his own work, because "that's the QA's job". Unsurprisingly, he didn't last very long.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#15
post #10

Earlier quoted context omitted.

The flip side of this (from my ~8 years of experience as a technical writer (TW)) is that once you hire a TW the natural tendency is for engineers to relinquish all responsibility of docs. The happy medium IMO is to put some responsibility for docs in the engineering ladder (not as a nice-to-have for promotion but a legit expectation) and to likewise have an expectation in the TW ladder that they cannot do all the do…

Serious question, if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it? You wouldn't expect TWs to dabble in the prod codebase.

If you have 1 TW and 50 devs, it will speed things up a lot if the devs can at least churn out the rough drafts and the TW can clean them up and link them together.

Learning to write documentation (which is really just trying to write them over a long period of time) is a skill that improves your overall communication skills. Devs should want to improve those skills (as everyone should), so they should want to write at least some docs.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#16

Not sure if this is specific to this book, or Apress in general, but it seems absurd that the eBook sells for $29.99, but you can also buy each chapter individually for $29.95? The $29.99 is more than reasonable as a price for the book. But who would be looking to spend the same price and receive only a chapter? Seems almost like some sort of trick to hopefully get a customer to unintentionally buy only a single chap…

It’s a decoy. https://hstalks.com/t/3538/the-economist-a-pricing-experimen...

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#17
post #10

Earlier quoted context omitted.

The flip side of this (from my ~8 years of experience as a technical writer (TW)) is that once you hire a TW the natural tendency is for engineers to relinquish all responsibility of docs. The happy medium IMO is to put some responsibility for docs in the engineering ladder (not as a nice-to-have for promotion but a legit expectation) and to likewise have an expectation in the TW ladder that they cannot do all the do…

Serious question, if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it? You wouldn't expect TWs to dabble in the prod codebase.

Because the developers are literally writing the source of truth for the docs. They know the information best, even if they aren't necessarily the best at presenting it or doing all of it. They certainly are the best for forming the rough draft of correct information.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#18
post #9

Not very much off-topic, I wish someone makes https://docusaurus.io as a service.

Docusaurus is a typical node-based SSG, you can easily run it on Netlify, Vercel, or other similar sites. They even have docs for how to do it: https://docusaurus.io/docs/deployment#deploying-to-netlify

Perhaps GP doesn't want to set up and maintain their own installation, which includes things like securing it and keeping the installation up-to-date with security patches and performance enhancements. It's completely reasonable to ask if someone is willing to provide it as a service and do the ops work in exchange for money. Saying "just install it here and run it yourself" strikes me as putting the burden on someone who has already expressed a desire to have someone else take on the work.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#19
post #10

Earlier quoted context omitted.

The flip side of this (from my ~8 years of experience as a technical writer (TW)) is that once you hire a TW the natural tendency is for engineers to relinquish all responsibility of docs. The happy medium IMO is to put some responsibility for docs in the engineering ladder (not as a nice-to-have for promotion but a legit expectation) and to likewise have an expectation in the TW ladder that they cannot do all the do…

Serious question, if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it? You wouldn't expect TWs to dabble in the prod codebase.

I can see the argument for the "Lead" model, where you have a single technical writer who takes a tech-lead-like responsibility for documentation and writing bit doesn't necessarily do it all themselves.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#20
post #16

Not sure if this is specific to this book, or Apress in general, but it seems absurd that the eBook sells for $29.99, but you can also buy each chapter individually for $29.95? The $29.99 is more than reasonable as a price for the book. But who would be looking to spend the same price and receive only a chapter? Seems almost like some sort of trick to hopefully get a customer to unintentionally buy only a single chap…

It’s a decoy. https://hstalks.com/t/3538/the-economist-a-pricing-experimen...

That's an awful website you've linked; pop ups on popups, obscuring alerts, all overlaying the content. Do you mind providing a short text comment about what a "decoy" is in this context?
Post reply on HN