Sometimes Dragons

Docs Roundup 1.3

Share via Twitter Share via Facebook Share via Linkedin Share via Reddit

Recent docs (and tech comm) items of interest: commit messages; new docs for Launch Darkly; questions of form and audience; some comics about Git

Illustration of 15th-century Burgundian scribe Jean Miélot writing at his desk. He is surrounded by a variety of manuscripts and writing implements.

Commit Messages

Comic panel showing a series of commits; the commit messages grow increasingly less useful (from

As this oft-cited xkcd comic illustrates, good commit messages can be difficult to compose, especially once the author is hours into a work session. And yet, a good commit message can save hours of detective work later on.

It is therefore important to have a set of commit message best practices established before starting work on a project or product. Whether you are working solo on your own project or looking to improve or standardize commit message practices for your team, these commit messages resources are worth a look:

Launch Darkly Docs 

Launch Darkly (a key player in the realm of Progressive Delivery, one of the 2020 focus areas for my colleague James) recently announced a rebuild of their documentation site:

The related blog post details the motivation for the rebuild and some of the processes involved:

Documentation is a core component of a robust product offering. Starting today, the LaunchDarkly product and SDK documentation site has a new look and new capabilities.

 

We used to use a third-party company to host and publish our docs site. This limited the documentation experience we could provide to our customers, end-users, and curious strangers. Now we have more options to improve navigation and information architecture, more consistent support for readers who use accessibility tools to read our docs, and a faster, more transparent toolchain that lets us edit the docs in a measurable, collaborative way.

 

How does this impact you? Besides lightning-fast load times and a sleeker, more modern UI, our publication toolchain is now based on products developers use, know, and trust.

The change also allows users who are familiar with Git and GitHub to contribute to the documentation: a growing trend among companies that are adopting docs as code practices (check out the 1.1 Docs Roundup for more docs as code examples).

Questions of form and audience

In a post on the different forms of software documentation, Daniele Procida writes:

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.

 

They are: tutorials, how-to guides, explanation and technical reference. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most software documentation – often immensely.

While these categories of different forms and their purposes are useful, so is this reminder (which resurfaced Procida’s post) that even something as seemingly narrow as software documentation can have multiple audiences:

With multiple audiences comes different starting knowledge bases, emphasizing the often difficult tech writing task of empathizing with users/readers who may not be already familiar with given technologies or processes. Indeed, the difficulty of writing for audiences that do not have the same knowledge base as the author is characterized by this article headline as “The Single Reason Why People Can’t Write.”

Miscellany

Worth 1000 words 

Have a recent/upcoming docs item you want me to know about? Drop me a line or find me on Twitter.

Disclosure: Launch Darkly, GitHub, and Microsoft are RedMonk clients.

Image information: Wikimedia Commons; image is in the public domain.

No Comments

Leave a Reply

Your email address will not be published.