Before my last company went through significant layoffs and furloughs during the COVID-19 crisis, I was putting together a plan to help revamp our internal documentation system. Like most systems, it went out of date quickly, and I was frustrated that best practices seemed to be hard to find. I’ve started putting together a list of best practices as I figure out how to put together a more holistic documentation perspective. This is a list of resources for others on the same path. Many of the books are not fully on documentation, but rather books I already had and pulled from for their relation to documentation.
Agile Documentation: A Pattern Guide to Producing Lightweigth 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.
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:
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.
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.
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.
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?