Docs for Developers: An Engineer’s Field Guide to Technical Writing
1–10 of 52 posts
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#2I 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.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#3I 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.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#4I 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.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#5Not 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.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#6I 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…
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.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#7You can read it with your ACM/O'Reilly subscription => https://www.oreilly.com/library/view/docs-for-developers/978...
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#8Writing well is underrated. Too many people think they do it well. Kind of like Dutch people and their command of the English language.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#9Not very much off-topic, I wish someone makes https://docusaurus.io as a service.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#10I 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…
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.