[HN Gopher] Docs for Developers: An Engineer's Field Guide to Te...
___________________________________________________________________
Docs for Developers: An Engineer's Field Guide to Technical Writing
Author : jabajabadu
Score : 68 points
Date : 2021-10-21 17:42 UTC (5 hours ago)
(HTM) web link (www.apress.com)
(TXT) w3m dump (www.apress.com)
| mactournier wrote:
| You can read it with your ACM/O'Reilly subscription =>
| https://www.oreilly.com/library/view/docs-for-developers/978...
| CameronBanga wrote:
| 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 wrote:
| It's a decoy. https://hstalks.com/t/3538/the-economist-a-
| pricing-experimen...
| kyleee wrote:
| 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?
| hanswesterbeek wrote:
| Writing well is underrated. Too many people think they do it
| well. Kind of like Dutch people and their command of the English
| language.
| mrwnmonm wrote:
| Not very much off-topic, I wish someone makes
| https://docusaurus.io as a service.
| qbasic_forever wrote:
| 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
| cratermoon wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| I've been quite happy to see Apple Pay spreading online, in
| part for that reason.
| teeray wrote:
| 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.
| cabbagehead wrote:
| 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.
| kaycebasques wrote:
| 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.
| ducharmdev wrote:
| 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.
| pc86 wrote:
| 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.
| 0xbadcafebee wrote:
| 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.
| kaycebasques wrote:
| > 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.
| xboxnolifes wrote:
| 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.
| dukeyukey wrote:
| 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.
| dragonwriter wrote:
| > 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.
| clumsysmurf wrote:
| 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.
___________________________________________________________________
(page generated 2021-10-21 23:00 UTC)