Over the last few years, this is a set of documentation advice I’ve come back to frequently.


Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects - Rüping, Andreas

I will get to a full review later, but like many of the other early agile books, that which is valuable has been accepted as common sense - most of the common commercial wikis turn sections 3 and 4 into “use a commercial wiki, set up common templates, and observe some basic organization principles.” I liked a lot about what the book said about how to create a documentation portfolio, but I think that the real missing link is a set of documentation patterns from which to draw. There is room for a new book here.

Applying UML And Patterns - Craig Larman

This is primarily a book about object oriented design, even though it takes a UML-centric focus for it. UML was given as one of the primary ways of documenting in the 90s, and it follows today, but between the tools we have to build it and the practicality of the documents it produces, it seems to have limited use. I think it’s worth thinking about why.

Tangential Books:

Software Architecture in Practice - Len Bass, Paul Clements, and Rick Kazman

Chapter 18 is dedicated to documenting software architectures, and is worth reading about within a larger context of documentation and architecture.

RESTful Web APIs - Leonard Richardson and Mike Amundsen

This is about the API layer, and is mostly a book on hypermedia, but it has a documentation component and as such is useful as a comparison to OpenAPI / Swagger approaches

Domain Driven Design - Eric Evans

Again, this is not a book about documentation, but the idea of domain driven design dovetails into documentation, and and it spent some time thinking about documents. I think the concept about the Domain Vision Statement will factor into more general patterns.

Thinking in Systems - Donella Meadows

Part of the problem of documentation is that our systems don’t encourage good documentation. Understanding systems and building feedback loops helps us think about how to build a system that builds good documentation.

General Technical Documention Articles and blogs:

Diataxis Framework - Daniele Procida. This is an incredible content framework for developer-facing documentation, whether or not it is internal or external-facing. At OneStudyTeam, we used this to provide clarity in the types of documentation we developed, and we were moving to Techdocs to more codify it.

Write The Docs guide - Write The Docs. This is an incredible resource to dive into what is necessary.

Technical Documentation in Software Development: Types, Best Practices, and Tools - Altexsoft. This is a long set of information about the types of documentation that larger systems require. It’s valuable as a set of targets to have.

18 Software Documentation Tools that Do The Hard Work For You - Process Street. Some tools that have already been developed to help software documentation, for a broad idea of “developed.”

Building better documentation - Atlassian. This is Atlassian’s guide to good documentation. This barely made the cut, as it’s rather sparse, but I liked its six step process as an example of the problem of how we describe documentation.

Why agile teams should care about documentation - Tom Thompson. The value is below in the “Making agile and documentation work together” section - it starts to consider what it looks to build a system that values documentation.

Core Practices for Agile/Lean Documentation - this is in the “write as little documentation as possible” camp, and it’s both rich with good and bad ideas. It feels like they are fighting against “documentation from above” and low-value documentation, but don’t really have an idea of how to build good ones. The idea that “documentation is a business decision” that he pulls from XP is thought provoking, but while the

Agile/Lean Documentation: Strategies for Agile Software Development is another from Scott Ambler (see above) has a similar perspective. Under Table 1, it shows potential documents to be created by the development team. The documents that he shows as more valuable are precisely the ones that have the least guidance. How can we build better internal documentation if we don’t have patterns for that?

10 things you can do to create better documentation - Alan Norton. This is more of a set of tips to keep in mind, but can inform a larger effort.

Internal Documentation 101: A Simple Guide to Get You Started - Josh Brown. This is a fantastic article that gives the steps to kickstart internal documentation efforts and informed the article on how to build a documentation culture. They are trying to sell you software, but it is translatable to other options.

API Documentation articles / blogs

Documenting Your Existing APIs: API Documentation Made Easy with OpenAPI & Swagger - Smartbear. This gets into how to use swagger, the most common form of API documentation.

Support Documentation

How to Build an Effective Support Knowledge Base: Everything You Need to Know about Documentation - Jess Byrne. It’s a good introduction to user-facing support documention. This doesn’t quite match what is needed for an internal support knowledge base, but there is overlap.

Operations documentation

How to Write a Killer Operations Manual [5 Easy Steps] - Tallyfy. Built from a Business Process Management perspective and partially to support buying Tallyfy, but it’s a good start about thinking of how to structure operations manuals. the links below that are seemingly valuable as well.

How to Write an Operations Manual - Edward Lowe Foundation. this is for non-technical audiences, and I think that’s what creates the value. It helps expand our thought of what needs to be in a tech company’s operations manual.

How To Document Your Current Processes In 10 Easy Steps - Quickbase. Can we build a similar 10 steps to how to document your current system?

Onboarding documentation

The Ultimate Guide to Onboarding New Developers: Industry Best Practices and How to Plan the First 90 Days - Nicole Kow. Onboarding documentation is a common pattern for the first 90 days. I think the self-actualization piece she points to is interesting conceptually, but it feels a little shoehorned into this. However, it has a good checklist of things to consider in the onboarding documentation.

What People Really Want from Onboarding - Tori Fica. Ironically, the infographic seems to be broken, but it has

System documentation

C4 Model - this seems to be the most used at this point.