Docs for Developers: An Engineer’s Field Guide to Technical Writing(apress.com)
apress.com
Docs for Developers: An Engineer’s Field Guide to Technical Writing
https://www.apress.com/gp/book/9781484272169
51 comments
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 docs themselves but rather need to develop systems/processes for collaborating with engineers. Basically what you said in your last sentence, just phrased differently.
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.
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.
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.
Translation for people who are unfamiliar with the acronym: SME seems to stand for “subject matter expert.”
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.
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.
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.
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.
> 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.
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.
I disagree. Documentation is about communication. How effective is an architect without communicating architecture?
If we consider a documentation system, maybe with guides, references, etc ... at minimum I would expect developers to clearly document APIs, database tables / schemas, contracts, and protocols.
A good example of developers not doing a good job here is the Android reference Javadocs... and I don't think this is the domain of technical writers.
If we consider a documentation system, maybe with guides, references, etc ... at minimum I would expect developers to clearly document APIs, database tables / schemas, contracts, and protocols.
A good example of developers not doing a good job here is the Android reference Javadocs... and I don't think this is the domain of technical writers.
>[...] clear writing is an indication of clear thinking [...]
I think this is technically true, but I tend to think of it more like "Attempting to write clearly will lead to clear thinking". It's hard to be sure you're thinking clearly until you've attempted to communicate it precisely.
I think this is technically true, but I tend to think of it more like "Attempting to write clearly will lead to clear thinking". It's hard to be sure you're thinking clearly until you've attempted to communicate it precisely.
I really value working with a good technical writer, but you can't always have that. I worked with one of the authors of this book briefly many years ago. This book encapsulates a lot of their experience, for writing developer docs, such as API docs.
Developer docs have a lot of conventions and it's useful to have them written down.
I've been applying the book's advice this week on my hosting platform's docs. For example, there's good advice for an information architecture, and the different content types to have it in it. The book's an easy and relatively quick read.
Developer docs have a lot of conventions and it's useful to have them written down.
I've been applying the book's advice this week on my hosting platform's docs. For example, there's good advice for an information architecture, and the different content types to have it in it. The book's an easy and relatively quick read.
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 chapter.
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 chapter.
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?
A Decoy is when you introduce an option in the menu that is "absurdly" or illogically priced, in order to make other options seem like a better deal. Some examples:
- Some restaurant menus will have 1-2 incredibly expensive entrees or appetizers. They know the volume on these items will be low, but they make other items seem less expensive by comparison.
- The most famous example is how the Economist did pricing for their online and print offerings -- The offered Online-only for $60, Print for $125, and Print + Online for $125. Obviously the Print-only option makes no sense, it's just there to make the Print + Online seem like a better deal, and push you away from the cheaper $60 offering. A less pop-up filled explanation is here: https://cxl.com/blog/pricing-experiments-you-might-not-know-...
- Some restaurant menus will have 1-2 incredibly expensive entrees or appetizers. They know the volume on these items will be low, but they make other items seem less expensive by comparison.
- The most famous example is how the Economist did pricing for their online and print offerings -- The offered Online-only for $60, Print for $125, and Print + Online for $125. Obviously the Print-only option makes no sense, it's just there to make the Print + Online seem like a better deal, and push you away from the cheaper $60 offering. A less pop-up filled explanation is here: https://cxl.com/blog/pricing-experiments-you-might-not-know-...
Thank you
What an interesting reaction.
You can read it with your ACM/O'Reilly subscription => https://www.oreilly.com/library/view/docs-for-developers/978...
I saw this book mentioned on twitter, the author(s) were hyping it. I'd love to buy the ebook but I don't want to have to register or accept any TOS, I just want to give money and download the epub format. Everywhere I've looked requires creating an account. I see it's available on Amazon but... well, I don't want Kindle format and also would prefer almost any other seller.
> I see it's available on Amazon but... well, I don't want Kindle format...
It's trivial to de-drm and convert a lot of ebooks.
You need Calibre (free/open source, gui [1]), its DeDrm plugin (free/open source, gui [2]), and its KindleUnpack plugin (free/open source, gui [3]). There's a guide [4], but the toolchain is all point/click, not a hassle at all to use.
> The DeDRM plugin handles books that use Amazon DRM, Adobe Digital Editions DRM (version 1), Barnes & Noble DRM, and some historical formats. The Obok plugin handles Kobo DRM.
For kindle books, it'll be less hassle over time if you install the Kindle app on your not-phone, not-tablet and just never update it. It'll just be a matter of import click + browse to the Kindle app's data folder and pick the most recent item after you buy one to instantly de-drm it and convert it to Epub. Amazon doesn't force upgrades of the app presently, and newer DRM schemes won't be pushed to you if your version doesn't support them.
1. https://calibre-ebook.com
2. https://github.com/apprenticeharper/DeDRM_tools/releases
3. https://github.com/dougmassay/kindleunpack-calibre-plugin/re...
4. https://www.epubor.com/free-kindle-drm-removal-calibre-plugi...
All of this is very well maintained and very well presented by the calibre community. Converting an Amazon format to Epub loses nothing in terms of functionality or aesthetics, the resulting Epubs in iBooks look identical to the drm versions on Kindle, and iBooks syncs notes/highlights across devices in non-drm Epubs just like Kindle does with its book formats (sans the public sharing of notes/highlights of course). The ability to embed your own metadata once the drm is gone is a nice plus as well.
It's trivial to de-drm and convert a lot of ebooks.
You need Calibre (free/open source, gui [1]), its DeDrm plugin (free/open source, gui [2]), and its KindleUnpack plugin (free/open source, gui [3]). There's a guide [4], but the toolchain is all point/click, not a hassle at all to use.
> The DeDRM plugin handles books that use Amazon DRM, Adobe Digital Editions DRM (version 1), Barnes & Noble DRM, and some historical formats. The Obok plugin handles Kobo DRM.
For kindle books, it'll be less hassle over time if you install the Kindle app on your not-phone, not-tablet and just never update it. It'll just be a matter of import click + browse to the Kindle app's data folder and pick the most recent item after you buy one to instantly de-drm it and convert it to Epub. Amazon doesn't force upgrades of the app presently, and newer DRM schemes won't be pushed to you if your version doesn't support them.
1. https://calibre-ebook.com
2. https://github.com/apprenticeharper/DeDRM_tools/releases
3. https://github.com/dougmassay/kindleunpack-calibre-plugin/re...
4. https://www.epubor.com/free-kindle-drm-removal-calibre-plugi...
All of this is very well maintained and very well presented by the calibre community. Converting an Amazon format to Epub loses nothing in terms of functionality or aesthetics, the resulting Epubs in iBooks look identical to the drm versions on Kindle, and iBooks syncs notes/highlights across devices in non-drm Epubs just like Kindle does with its book formats (sans the public sharing of notes/highlights of course). The ability to embed your own metadata once the drm is gone is a nice plus as well.
I'm aware of all that and have been using Calibre for some time. That's not the solution I want to deal with. I would prefer to encourage authors and publishers to reduce friction for their potential readers and make their work available through less predatory means. Even though you and I may have the knowledge and ability to work through that friction, other people may not.
I've been quite happy to see Apple Pay spreading online, in part for that reason.
Apply Pay just shifts the registration and need to agree to a TOS to another party. Whatever happened to just "here's some cash money"? I've already got a bank account and credit cards, they already have my business. Just let me use them to buy your product.
The trick with Apple Pay is that supposedly you have already accepted Apple's TOS and they already have your cards so you do not need additional registrations.
In Apple's grand, glorified vision that should be the only one you need.
In Apple's grand, glorified vision that should be the only one you need.
How, exactly, is it that I've already accepted Apple's TOS? When did that happen? Why do they already have my cards?
Because to use Apple Pay you also need to have your cards in your Apple Wallet. Cant remember exactly the onboarding process for this but I guess there are a few checkboxes to check.
I don't have Apple Wallet. How did Apple get my cards an info?
Because you are supposed to want to use Apple Pay! :D
Writing well is underrated. Too many people think they do it well. Kind of like Dutch people and their command of the English language.
What's that about? I'm a native English speaker and know a few Dutch people but haven't noticed some effect like that.
Not the original commenter, but I’ve heard, and somewhat observed, that Dutch people are generally more fluent in English than other Europeans; and I’ve heard this attributed to Dutch television, where English shows are generally presented in English but with Dutch subtitles, unlike other European nations where such shows would be dubbed into the local language.
While that plays a role, it's a bit odd to single out Dutch for that - far from the only European country where that is the case.
Also a bit glossing over the details if we consider how close Dutch and English are compared with say Slavic languages and English or Latin languages and English.
I remember reading a while back that Old English and Old Frisian would have been mutually understandable. Although in fairness I doubt most Dutch today would follow a conversation in Frisian.
I remember reading a while back that Old English and Old Frisian would have been mutually understandable. Although in fairness I doubt most Dutch today would follow a conversation in Frisian.
Lots of talk about documentation in this thread but returning to the book: has anyone read it or seen an independent review yet? I've seen the authors hyping its release; now I want to know if it's any good :)
They are clearly so good at documentation that they link to a book rather than to a site with the actual docs.
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
Thanks for the reference. But if you would allow me to be honest, I don't want to even read that page. I have tons of things to do, I want to just write. I am using Gitbook right now but I like Docusaurus more. I hope if someone would enhance the design a little bit, and give me the ability to add custom CSS if I really wanted to. And I am happy to pay for it a reasonable price.
I could actually just install it locally, do whatever I want, generate the static files, and add it to my project. But I will have to maintain the installation (for a language that I don't use), keep it updated, maybe fight with npm for sometime, and also being familiar with Docusaurus itself.
And I prefer a service focused on this problem, than using a general (even if easier) solution like Netlify.
At the end of the day, I think I will do what you said, because that service doesn't exist now :)
I could actually just install it locally, do whatever I want, generate the static files, and add it to my project. But I will have to maintain the installation (for a language that I don't use), keep it updated, maybe fight with npm for sometime, and also being familiar with Docusaurus itself.
And I prefer a service focused on this problem, than using a general (even if easier) solution like Netlify.
At the end of the day, I think I will do what you said, because that service doesn't exist now :)
Check out Netlify, I think you'd really like its build previews. Basically go through a teeny bit of pain once to set it up and then all you have to do is push updated documentation files to github. Netlify will detect the changed files, rebuild your site using docusaurus, and send you a URL to hit to immediately view the updated docs as a preview. If you like it you click a button and make it live, otherwise you go back and edit and revise. You don't need to janitor or babysit a local install after the initial setup. Check out more info in some of their tutorials: https://www.netlify.com/blog/2016/09/29/a-step-by-step-guide...
I will, thanks very much.
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.
I think you should look into what Netlify actually does--you seem to be misunderstanding it as a typical hosted compute platform like EC2. With Netlify and similar service it's actually more like AWS lambda but tightly integrated into git/github. You push all your content source to github and setup a webhook that notifies Netlify of any change. Every time you commit Netlify will pull down your content, run your static site generator (docusaurus) in an ephermal container (like a lambda function) and then save the resulting generated content/HTML to their hosting site. At no time are you running or managing or operating an actual server.
As best I can tell, and I'm willing to be proven wrong, to tell Netlify which static site generator to run, the configuration must specify the command. Unless Netlify is maintaining the version/container/build of whatever command is given, it's up to the site owner to provide that. Thus, it's on the site owner to specify a build command that doesn't introduce undesirable or malicious behavior.
It's a nodejs app using a standard package.json which captures all of the dependencies (including docusaurus version, etc.). Netlify detects the package.json, loads a container with node, installs the dependencies and goes to work. You don't need to manage anything. See more details: https://docs.netlify.com/configure-builds/manage-dependencie...
I don't see anything there that says Netlify is managing or maintaining the details. The customer provides the package.json, If that file contains a reference to a library or code that introduces bugs or vulnerabilities, it's on the customer. Thus it still puts the burden of maintenance on the customer.
In a managed SaaS installation, the customer would be paying for the functionality of, say, docusaurus, but the company would provide and maintain the dependencies. It's the difference between paying for a server to run a version of mysql you specify and paying a service to run mysql and keep it in a known good configuration while the customer is able to use mysql.
In a managed SaaS installation, the customer would be paying for the functionality of, say, docusaurus, but the company would provide and maintain the dependencies. It's the difference between paying for a server to run a version of mysql you specify and paying a service to run mysql and keep it in a known good configuration while the customer is able to use mysql.
Question, which online documentation do you consider great?
I quite like the Stripe documentation and wished they open-sourced it. Any others?
It passed through HN ~9 months ago [1], where kaycebasques stated, "I think the key breakthrough with Divio's framework is getting authors to think about docs in terms of desired goals and outcomes: learning-oriented, problem-oriented, etc."
[0]: https://documentation.divio.com
[1]: https://news.ycombinator.com/item?id=26002656