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

Commit Messages

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:

• Using Git Commit Message Templates to Write Better Commit Messages: a template from Lisa Wold Eriksen that incorporates a number of best practices. 
• How to Write a Git Commit Message: a post from Chris Beams that breaks down why good commit messages matter and how to produce them.
• The Art of the Commit by David Demaree: discusses commit message process, elements of style, and has a nice take on framing the log message as a headline. 
• How to Write Useful Commit Messages (My Commit Message Template): a recent post AND template from Jacob Herrington that is part of a larger Git Guide series.

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:

An incredible team @LaunchDarkly rebuilt our docs site and I'm so excited and proud of what we've accomplished.

The new Github-based workflow lays the foundation for a more vibrant community around our docs. Check it out! Leave us a PR! HOORAY!https://t.co/s2RWkyiK6k

— Sarah Day (@scribblingfox) February 14, 2020

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:

And then an explanation of the DIFFERENT DOC TYPES YOU NEED for projects aimed at developers/data scientists/sysadmins/DBAshttps://t.co/StxmpkwZx5

Courtesy of @evildmp

— (((TheSteve0))) @[email protected] (@TheSteve0) February 14, 2020

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

• Linode surfaced this interview with Rajakavitha Kodhandapani (Developer Advocate at Linode and Co-chair of K8s Usability SIG) on documentation as a way to contribute to open source projects. 
• ICYMI (I certainly did), Shane Boyer wrote up a lovely post to point out that Microsoft docs team publishes a monthly writeup on “.NET documentation – what’s new?” 
• This thread on business writing (surfaced by Erica Brescia).
• Twitter thread of interest: Dr. Halcyon Lawrence is looking for “a repository of CFPs (conferences, special issues etc.)” in technical communication.   
• Dr. Kathleen Kennedy (a fellow medievalist who found themselves teaching tech comm) on how we “STILL manage to sacralize the  author” (even in tech writing).

Worth 1000 words 

Git Flow! 
P.S. Here's an intro to #Git: https://t.co/oVWPLIrSGi pic.twitter.com/1odzzerl58

— A Cloud Guru | A Pluralsight Company (@acloudguru) February 12, 2020

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.