• July 2019
    S M T W T F S
    « Sep    
  • Facebook

Posts Tagged "api-doc"

Review of Andrew Etter’s ebook on Modern Technical Writing

Listen to this post:

You can download the MP3 file or subscribe in iTunes.


Recently to try to get better sleep, I switched from reading my iPhone at night to a Kindle E-reader. It turns out I really like reading from the Kindle E-reader, so much that I actually bought two of them (the Paperwhite and the Voyager). Reading from the Kindle feels more offline, so I can get immersed more fully in the content, rather than flipping back and forth between email, Reddit, Twitter, or other sites.

While reading on my Kindle, I stumbled across a book called Modern Technical Writing: An Introduction to Software Documentation, by Andrew Etter, published in 2016. It’s is actually a short book (10,000 words), and you can read it about a half hour.

Modern Technical Writing, by Andrew Etter
Modern Technical Writing, by Andrew Etter

Who is Andrew Etter? He provides almost no biographical details about himself in the book, but based on my Linkedin search, he seems to be a lead writer at Palantir, which is a company in the Bay area that I actually toured when I moved out here.

Andrew’s book should be required reading for every technical writer, both experienced and novice. I’ve never felt more at home reading a tech comm book than I have with Modern Technical Writing.

Admittedly the book is short, but this is good. It means he doesn’t pad it with extra fluff to achieve a book-length word count. He jumps straight to the point and writes with such an easy-to-follow, conversational voice that I couldn’t help but just like the guy.

What does it mean to do “modern” technical writing? From a technical angle, Etter argues that one should embrace lightweight markup languages, use static site generators, and store content in version control repositories with engineering code. Etter also argues that writers should spend most of their time researching and testing content, investigating analytics, and iterating on the doc content on their websites.

Contributors and lightweight markup languages

With regards to documentation formats, Etter writes:

… one of the tenets of modern technical writing is that everyone is a contributor. Storing content directly in XML-based languages like XHTML, DocBook, and DITA dramatically reduces people’s ability to contribute…. Rather than being mere deterrents (like writing in XML), specialized applications actually prevent people from contributing. Amazing text editors are available on every operating system, mostly for free, and writers can use whichever they like. … For documentation, lightweight markup is free and superior in every meaningful way.

Etter compares a simple passage in written in AsciiDoc with the same passage in Docbook. The Docbook passage is about about 7 times longer than the AsciiDoc passage and contains so many nested tags it’s nearly unreadable.

Rather than embrace the lightweight formats for simplicity, Etter says technical writers need to encourage contributions from those who have deep, helpful product knowledge. He says,

The reality of the profession is that even a large team of writers cannot possibly know everything worth knowing about an application, and most companies do not have a large technical writing team. The open-source software movement, mod scene in PC games, and birth of a million obscure wikis have proven that people will happily share their expertise and passion if an easy, hospitable way of doing so exists.

Static site generators

Etter also advocates using static site generators for documentation platforms, especially Sphinx because it has built-in search and sidebar navigation. Etter devotes a good part of the book to static site generators, explaining:

I have perhaps an irrational bias towards static websites. I love them. I love their speed, simplicity, portability, and security. You can host static websites practically anywhere…. They have no server-side application dependencies, no databases, and nothing to install, so migrating the entire site is as easy as moving a directory.

Websites instead of PDF

Etter also discourages spending time generating PDFs. With PDFs, users inevitably save the PDF files to their computers, and then rely on them even when the PDFs are out of date. In contrast, by publishing to a website, you can continually iterate on your content and make updates to correct misinformation or add missed content. Etter says,

I mentioned earlier that you should build and host a website, not distribute PDFs, but it bears repeating. Even the best documentation, like software, eventually goes out of date. PDFs get downloaded onto hard drives and then sit there like day-old bagels, growing more and more stale until they’re actively harmful. You can never update them. … The whole situation gives me the chills. Hosting your content on a website gives you the power to fix inaccuracies almost instantly and keep your content in sync with the latest software releases.

Etter perfectly captures all the complaints I’ve voiced about PDFs in so many posts. Reading this, I felt like cheering and celebrating inside. His message is clear: Modern technical writers do not spend time writing and publishing lengthy PDFs, because people prefer to go online for more up-to-date information.

I should note that, as the book’s subtitle indicates (“An Introduction to Software Documentation”), Etter is focusing on the software industry, which is an easier use case for dismissing PDF.

Version control systems

It should come as no surprise that along with using lightweight markup languages like AsciiDoc and Markdown, static site generators, and building websites instead of PDFs, Etter also recommends using distributed version control systems, such as Git or Bitbucket, to store documentation. Etter writes,

If you have the opportunity to store your documentation in the same repository as its corresponding product source code, strongly consider doing so. The approach has some real appeal:

  • Documentation and code branches stay in sync.
  • Developers are more likely to contribute if they don’t have to clone a separate repository.

Etter compares Git with Bitbucket, as well as interacting with these repositories through GUI clients and the command line. Etter also says that if it makes sense, you should also store your doc content in the same repository as the code, since it reduces documentation drift and encourages contribution.

How to spend your time

Beyond a discussion of tools and workflows, Etter offers some advice for writing good content. He says,

… producing content that people will read and find useful is, like, really hard.

Instead of writing all day, Etter says technical writers should spend 90% of their day learning (through testing and research), and only 10% writing. You write only after you have a good understanding of how the system works.

In a section called “Don’t Write,” Etter explains:

Technical writers, first and foremost, are testers and researchers. Your job is to know what people want to achieve and precisely how to achieve it. Communicating that knowledge is the last step of the process and really shouldn’t comprise more than 10% of your time.

Figuring out what to write does require a lot of time and effort. But it’s not so much figuring out how something works as much as determining what information is relevant to users. In a sea of possible product information, what do users actually need or want to know?

Grinding out knowledge

Finally, Etter says,

Technical writers need to be grinders, willing to slowly but surely chip away at the block of ignorance until a beautiful sculpture emerges – or something like that, anyway.

Little by little, one procedural step at a time, we chip away at ignorance and build a body of useful documentation that users find helpful.


In a concise 10,000 word ebook, Etter articulates a unified approach that provides an alternative to the XML + Component Content Management System approach that is so commonly advanced in tech comm circles. To summarize, this approach includes the following:

  • Lightweight markup languages
  • Static site generators
  • Integration with engineering code
  • Contributions from experts
  • Storage in distributed version control systems
  • Testing and researching more than writing
  • Websites instead of PDFs
  • Constant iteration and updating of content

We have far too many books espousing the benefits of XML and championing component content management systems as the model for contemporary tech comm solutions. These models seem outdated and part of another era, one that will eventually be replaced by this lightweight, more flexible, developer-centric approach towards documentation.

For now this modern model seem more applicable to small teams and companies, particularly with developer documentation, but who’s to say that the model won’t grow to fit large-scale teams and companies as well.

Where to get the book

You can read Modern Technical Writing here on Kindle. If you have a Kindle Unlimited subscription, it’s free. (If not, it’s $3.99.)

By the way, if you’re thinking of buying a Kindle E-Reader, I recommend the Kindle Paperwhite).

If you don’t have a Kindle, there are a lot of Kindle reading apps you can use on your smartphone or even the cloud.

Back to Top | Comments Off on Review of Andrew Etter’s ebook on Modern Technical Writing

Thoughts on “Transforming Documentation Processes” presentation at WTD: Evaluating the trend to treat documentation as code

You can watch the Transforming Your Documentation Process presentation here:

The panelists were Leon Barnard (@leonbarnard), Zach Corleissen (@zachorsarah), Ted Hudek (@tedhudek), and John Bulava (@jbulava).

(It’s funny that WTD lists the Twitter handle for each participant – in reality they should list the slack handle of the person on the WTD Slack channel.)

Riona started the panel by posing the problem that started her documentation transformation journey at Google. In internal tech surveys at Google, employees noted that documentation was hard to find. When you did find it, it was often incomplete or inaccurate. As a result, you didn’t know if you could trust the documentation (it might be outdated).

Riona said the survey’s findings closely paralleled those from the 2016 Developer Survey on Stack Overflow, which found that poor documentation was one of the greatest challenges in the workplace:

According to the 2016 Developer Survey on Stack Overflow, the second greatest challenge in the workplace is poor documentation.

50,000 developers took the survey on Stack Overflow. Even if the sample is biased toward people who are inclined to value good documentation (and hence provide informaton / survey responses on Stack Overflow), it’s hard to dismiss the results about the importance of documentation to developers.

As more support for the value of docs, a 2013 survey conducted by Programmableweb (which included about 250 developers) also found that “complete and accurate documentation” was the most important factor in an API:

Good documentation is the most important factor in an API

(As exciting as it is to find these surveys, don’t get too excited – few people seem to take them seriously, as evidenced by the steady decline or flatlining of employed tech writers. But let’s not dwell on that.)

The four panelists Riona chose all moved their documentation process toward openness and collaboration in similar ways:

  • Leon implemented Hugo, a static site generator, along with Swiftype for search. In their new model, customer support agents contribute content directly using text editors and commits.
  • Zach at Rackspace implemented a number of open source tools (which process Markdown) to leverage contributions and involvement with developers. The writers at Rackspace process hundreds of pull requests each month from contributing developers.
  • Ted at Microsoft moved toward another open model involving Markdown with a repository. Anyone can contribute docs, and contributing developers have a lively, quick process that seems to have a tremendous momentum.
  • John at Twitter is moving away from their Drupal environment and looking into Sphinx and other similar processes (though he’s still in the conceptual stage). Twitter apparently gave a seminal talk at last year’s WTD conference that influenced a great many attendees to embrace docs as code.

Referring to these transformation trends, Riona said there is “change in the air” – you can feel it in the breeze and on the water. Without question, many writers are moving towards a model that treats doc as code, closing the gap between engineering and tech comm, primarily integrating documentation into Github repositories and other code workflows with engineers.

The idea is to put docs in a space developers will look at and feel comfortable interacting in. This enables developers to easily make doc updates themselves and fosters more collaboration and community by having an open contribution process. These visionary writers want to move away from the model where only a few technical writers are allowed editorial access into the inner documentation sanctum.

But will treating docs as code achieve these technical writers’ goals? With Riona’s model, she says she’s having success. She looks at code commits and analyzes the number of times developers update the readme file when pushing updates. She finds that developers are updating the readme about a third of the time. This is because the docs are literally embedded in the code repositories, exactly where engineers prefer to work.

I wrote more about Riona’s doc process and previous WTD presentation here. If you haven’t listened to her talk, definitely do so. It’s inspiring.

Riona works in internal documentation for engineers. Will these other writers, who are more focused on external docs, be as successful in their efforts? Is the “docs as code” trend just another documentation fad, something to come and go, like wikis, or DITA? (ha ha)

More importantly, will treating docs as code actually solve any of the problems about documentation being poor, incomplete, and hard to find?

Although I’m a passionate Jekyll user and advocate treating docs as code, I’m wary about over-hyping this trend, as I don’t think it will actually solve the problems in a significant way.

Case in point, look at wikis. 10 years ago, wikis were all the rage. Wikis were (and still are) the epitome of openness and collaboration. They invite anyone to write, publish, and share information. But for some reason, wikis didn’t stick. About their only success is in replacing Sharepoint for internal information platforms at companies. (For more detail about why wikis failed, see When wikis succeed and fail.)

If wikis didn’t take off, why do we think this more current transformation process – writing docs in code repositories using text editors and following Markdown syntax – is going to be any more successful? Maybe Riona’s use case is too specific to internal engineering documentation only?

And if wikis didn’t inspire everyone at the company to contribute, what will inspire them? Why didn’t the wiki model prove to be a successful catalyst for enabling openness, information sharing, and doc contributions?

I don’t mean to completely undervalue success of wikis. Nearly every company has a wiki, and even though no one can ever find anything on it, people continue to add information to it. But very few wikis are used as external documentation platforms. Splunk and Genesys are some exceptions I know of (they use Ponydocs, a fork of Mediawiki).

99% of engineers have absolutely no interest in dedicating the lengthy amount of time needed to write, edit, and maintain documentation on a regular basis. This is precisely why technical writers exist. If engineers loved to write docs, we would not have jobs.

Even if engineers do want to write, they don’t have time for it. Look back at the Stack Overflow survey – the number one challenge is “unrealistic expectations.” Companies expect engineers to work little miracles each day, turning out new APIs and software applications overnight rather than over a period of months or years. (See my post, Why “Programming Sucks” and the fallacy of documentation in the context of code chaos for more details about why programmers have little time to spend writing documentation.)

I do think the move toward docs as code is positive, if only because the open source model is compelling and preferable to vendor lock-in, proprietary platforms, expensive tooling, black boxes, marketing, and other characteristics of the old guard model. (That’s another post, though.)

The reason the whole tech comm community hasn’t jumped onto the docs-as-code bandwagon is because it has yet to decidedly prove itself. It’s still novel – interesting and fun to use software engineering tools and workflows with docs, but the payoff? It helps tech writers get closer to engineering, for sure, and that proximity of environments is helpful.

At the end of the day, though, good documentation – the kind engineers would find helpful, credible, and productivity-enabling – is hard to write. It takes time and a lot of research to pull together code samples and good comments, sample apps, visual diagrams, tutorials, clearly articulated and logical concepts, easy-to-follow tasks, Hello World tutorials, and more.

Once published, maintaining docs requires regular updates, constant vigilance, and more. You need to keep aware of forum threads, support cases, newly added tickets, code changes, and more. All of this takes time and perseverance.

Good documenation is not easy to write – too often we’re look for a magic bullet with tools to solve our problems. Tools won’t solve the problem of poor documentation. At times tools alleviate some of the burdens of the authoring process, but at the end of the day, it’s the content you create that determines whether your documentation is helpful or not. Tools do not create content. People do.

Back to Top | Comments Off on Thoughts on “Transforming Documentation Processes” presentation at WTD: Evaluating the trend to treat documentation as code

Why “Programming Sucks” and the fallacy of documentation in the context of code chaos

You can read Peter Welch’s essay here: Programming Sucks.

Welch starts by responding to criticisms of friends who work in manual labor fields and assume that a programmer’s life consists of sitting calmly at a desk, playing on a computer all day. Welch’s main argument is that programming can be just as hellish as the worst manual labor job, but the hell isn’t in the physical exhaustion as much as the mental insanity you have to endure.

More than anything, Welch’s tone is playful and full of images, turns of phrases, and the raw, blunt honesty that tends to define programming culture. Here’s a passage:

Websites that are glorified shopping carts with maybe three dynamic pages are maintained by teams of people around the clock, because the truth is everything is breaking all the time, everywhere, for everyone. Right now someone who works for Facebook is getting tens of thousands of error messages and frantically trying to find the problem before the whole charade collapses. There’s a team at a Google office that hasn’t slept in three days. Somewhere there’s a database programmer surrounded by empty Mountain Dew bottles whose husband thinks she’s dead. And if these people stop, the world burns. Most people don’t even know what sysadmins do, but trust me, if they all took a lunch break at the same time they wouldn’t make it to the deli before you ran out of bullets protecting your canned goods from roving bands of mutants.

If you followed my previous blog post, Thoughts on “Documentation Avoidance for Programmers”, this article makes a nice juxtaposition. Why is programming such a hellscape to navigate? Well it doesn’t take a genius to put two and two together: When no one documents anything, you end up with a lot of code that no one understands, and hell’s bells start ringing.

Welch explains that despite one’s expertise, no programmer fully understands how even his or her own computer works, and only has a modicum of expertise around a small fraction of the technology he or she needs to know:

You are an expert in all these technologies, and that’s a good thing, because that expertise let you spend only six hours figuring out what went wrong, as opposed to losing your job. You now have one extra little fact to tuck away in the millions of little facts you have to memorize because so many of the programs you depend on are written by dicks and idiots.

And that’s just in your own chosen field, which represents such a tiny fraction of all the things there are to know in computer science you might as well never have learned anything at all. Not a single living person knows how everything in your five-year-old MacBook actually works. Why do we tell you to turn it off and on again? Because we don’t have the slightest clue what’s wrong with it….

Would good documentation solve the problems that Welch describes in “Programming Sucks”? Only partially. It’s not just that code is undocumented, but that the approaches programmers have to take to solve problems don’t follow straightforward logic.

Instead of a precise and principled engineer who writes clear, logical, easy-to-follow code that follows best practices and techniques, programmers are forced into all kinds of crazy scenarios where they have to detour away from good practices to satisfy nutty business requirements. They have to merge disparate systems and tools in new, innovative/insane ways. They have to hack together makeshift, often temporary solutions where none exist because software is due for release and project managers demand working code despite the unworkability of the coding language for the scenario.

In short, programming isn’t a clear and logical exercise. It’s an art where someone jerry-rigs a solution that miraculously works though it’s built on a bit of mystery and good luck – until it breaks, and then the programmer moves into all-night figure-it-out modes consuming lots of sugar and becoming more and more snarky and dark.

On the other side of the fence, documentation strives to be clear, logical, and precise. Technical writers insist on 1-2-3 step approaches following a linear sequence. Our job is to bring order to the chaos.

To do so, we have to construct somewhat of a narrative fallacy. The narrative fallacy is the illusion that a story develops along a clear and straightforward path based on a coherent idea or pattern (or in the context of documentation, that following these “easy” steps will achieve your goal) even when reality suggests much the opposite – that motives are fuzzy, things happen somewhat randomly, decisions and epiphanies might be made in retrospect (or not at all), and the events can’t be neatly plotted against an underlying principle or overarching lesson, nor are they connected or linear. Life is messy, and events have no meaning. There is no 1-2-3 step task to reach a goal. Programmers follow a mostly obscure path that takes them through many dark forests before the randomly stumble upon a brief opening that provides a change of view.

And yet, when you read something, especially documentation, you expect logic. You want a clear line of thought. We’re taught from gradeschool on up that all writing begins with a thesis, an assertion which is then carefully supported in each of the following paragraphs. Each paragraph has a central idea that all ties back to this thesis or argument.

But programming isn’t like this clear line of logic – at least according to Welch’s article. Good code, Welch explains, is an illusion. Good code only exists in a special file on your computer that you occasionally open and read to calm your nerves, and then you have to close that file of good code and return to the duct tape, glue, and madness that is your reality.

Is documentation, then, an illusion? A fiction that forces a narrative fallacy onto a programmer’s world, not entirely describing the programmer’s true task and challenges, and in so doing causes programmers to reject documentation (as well as writing it) in the first place? I think in part, yes.

I’m not suggesting that documentation try to let go of that clear line pointing from A to B, but there might be something to the chaos of code that runs counter to the task-based steps we so carefully like to draw out. Perhaps we should not insist so sharply on the [fictitious?] steps in our documentation? Then again, perhaps this idea of order in documentation is the only thing that keeps programmers from entering total insanity.

Back to Top | Comments Off on Why “Programming Sucks” and the fallacy of documentation in the context of code chaos

Other Stuff