8 ms·

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

184 points by jabajabadu 5y ago

cratermoon 5y ago
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.
- macintux 5y ago
  I've been quite happy to see Apple Pay spreading online, in part for that reason.
  - cratermoon 5y ago
    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.
    - pantulis 5y ago
      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.
      - cratermoon 5y ago
        How, exactly, is it that I've already accepted Apple's TOS? When did that happen? Why do they already have my cards?
        pantulis 5y ago
        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.
        cratermoon 5y ago
        I don't have Apple Wallet. How did Apple get my cards an info?
        pantulis 5y ago
        Because you are supposed to want to use Apple Pay! :D
- RNCTX 5y ago
  > 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 https://calibre-ebook.com 2. https://github.com/apprenticeharper/DeDRM_tools/releases https://github.com/apprenticeharper/DeDRM_tools/releases 3. https://github.com/dougmassay/kindleunpack-calibre-plugin/releases https://github.com/dougmassay/kindleunpack-calibre-plugin/re... 4. https://www.epubor.com/free-kindle-drm-removal-calibre-plugin.html 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.
  - cratermoon 5y ago
    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.
teeray 5y ago
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.
- clumsysmurf 5y ago
  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.
- kaycebasques 5y ago
  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.
  - pc86 5y ago
    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.
    - dragonwriter 5y ago
CameronBanga 5y ago
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.
- jkbr 5y ago
  It’s a decoy. https://hstalks.com/t/3538/the-economist-a-pricing-experiment/ https://hstalks.com/t/3538/the-economist-a-pricing-experimen...
  - kyleee 5y ago
    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?
    - jljljl 5y ago
      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-but-can-learn-from/ https://cxl.com/blog/pricing-experiments-you-might-not-know-...
      - kyleee 5y ago
        Thank you
mactournier 5y ago
You can read it with your ACM/O'Reilly subscription => https://www.oreilly.com/library/view/docs-for-developers/9781484272176/ https://www.oreilly.com/library/view/docs-for-developers/978...
hanswesterbeek 5y ago
Writing well is underrated. Too many people think they do it well. Kind of like Dutch people and their command of the English language.
- geomark 5y ago
  What's that about? I'm a native English speaker and know a few Dutch people but haven't noticed some effect like that.
  - LeonB 5y ago
    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.
    - detaro 5y ago
      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.
      - DoingIsLearning 5y ago
        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.
    - agent327 5y ago
      Mr. Westerbiek is saying that Dutch people think they're better at English than they generally are. Or maybe I misunderstood that? I'm Dutch, so who knows...
mrwnmonm 5y ago
Not very much off-topic, I wish someone makes https://docusaurus.io https://docusaurus.io as a service.
- qbasic_forever 5y ago
  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 https://docusaurus.io/docs/deployment#deploying-to-netlify
  - cratermoon 5y ago
    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.
    - qbasic_forever 5y ago
      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.
      - cratermoon 5y ago
        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.
infogulch 5y ago
I like linking to this site [0], the "The Grand Unified Theory of Documentation" that describes four categories of documentation that fill out a 2D space of potential docs value: the practical steps <-> theoretical knowledge dimension, and the useful when studying <-> useful when working dimension. * Tutorials - Learning-oriented - (practical/studying) * How To Guides - Problem-oriented - (practical/working) * Explanations - Understanding-oriented - (theoretical/studying) * Reference - Information-oriented - (theoretical/working) 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 https://documentation.divio.com [1]: https://news.ycombinator.com/item?id=26002656 https://news.ycombinator.com/item?id=26002656
porker 5y ago
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 :)
- encryptluks2 5y ago
  They are clearly so good at documentation that they link to a book rather than to a site with the actual docs.
wdb 5y ago
Question, which online documentation do you consider great? I quite like the Stripe documentation and wished they open-sourced it. Any others?

184 points by jabajabadu 5y ago

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.

macintux 5y ago
I've been quite happy to see Apple Pay spreading online, in part for that reason.
- cratermoon 5y ago
  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.
  - pantulis 5y ago
    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.
    - cratermoon 5y ago
      How, exactly, is it that I've already accepted Apple's TOS? When did that happen? Why do they already have my cards?
      - pantulis 5y ago
        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.
        cratermoon 5y ago
        I don't have Apple Wallet. How did Apple get my cards an info?
        pantulis 5y ago
        Because you are supposed to want to use Apple Pay! :D
RNCTX 5y ago
> 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 https://calibre-ebook.com 2. https://github.com/apprenticeharper/DeDRM_tools/releases https://github.com/apprenticeharper/DeDRM_tools/releases 3. https://github.com/dougmassay/kindleunpack-calibre-plugin/releases https://github.com/dougmassay/kindleunpack-calibre-plugin/re... 4. https://www.epubor.com/free-kindle-drm-removal-calibre-plugin.html 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.
- cratermoon 5y ago
  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.

teeray 5y ago

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.

clumsysmurf 5y ago
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.
kaycebasques 5y ago
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.
- pc86 5y ago
  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.
  - dragonwriter 5y ago

CameronBanga 5y ago

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.

jkbr 5y ago
It’s a decoy. https://hstalks.com/t/3538/the-economist-a-pricing-experiment/ https://hstalks.com/t/3538/the-economist-a-pricing-experimen...
- kyleee 5y ago
  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?
  - jljljl 5y ago
    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-but-can-learn-from/ https://cxl.com/blog/pricing-experiments-you-might-not-know-...
    - kyleee 5y ago
      Thank you

mactournier 5y ago

You can read it with your ACM/O'Reilly subscription => https://www.oreilly.com/library/view/docs-for-developers/9781484272176/ https://www.oreilly.com/library/view/docs-for-developers/978...

hanswesterbeek 5y ago

Writing well is underrated. Too many people think they do it well. Kind of like Dutch people and their command of the English language.

geomark 5y ago
What's that about? I'm a native English speaker and know a few Dutch people but haven't noticed some effect like that.
- LeonB 5y ago
  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.
  - detaro 5y ago
    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.
    - DoingIsLearning 5y ago
      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.
  - agent327 5y ago
    Mr. Westerbiek is saying that Dutch people think they're better at English than they generally are. Or maybe I misunderstood that? I'm Dutch, so who knows...

mrwnmonm 5y ago

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

qbasic_forever 5y ago
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 https://docusaurus.io/docs/deployment#deploying-to-netlify
- cratermoon 5y ago
  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.
  - qbasic_forever 5y ago
    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.
    - cratermoon 5y ago
      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.

infogulch 5y ago

I like linking to this site [0], the "The Grand Unified Theory of Documentation" that describes four categories of documentation that fill out a 2D space of potential docs value: the practical steps <-> theoretical knowledge dimension, and the useful when studying <-> useful when working dimension. * Tutorials - Learning-oriented - (practical/studying) * How To Guides - Problem-oriented - (practical/working) * Explanations - Understanding-oriented - (theoretical/studying) * Reference - Information-oriented - (theoretical/working) 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 https://documentation.divio.com [1]: https://news.ycombinator.com/item?id=26002656 https://news.ycombinator.com/item?id=26002656

porker 5y ago

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 :)

encryptluks2 5y ago
They are clearly so good at documentation that they link to a book rather than to a site with the actual docs.

wdb 5y ago

Question, which online documentation do you consider great? I quite like the Stripe documentation and wished they open-sourced it. Any others?