Book review of 'Docs-as-Ecosystem'

Posted on 4 mins read

A review of the book Docs-as-Ecosystem by Alejandra Quetzalli.

Summary

This book teaches readers how mastering the docs-as-code ecosystem empowers communities to better understand products and open source technologies. The author believes that “docs-as-ecosystem” represents a more comprehensive and collaborative approach to documentation development than docs-as-code because it recognizes that documentation is more than just code. Docs involve technical writing, design, feedback, information architecture, accessibility, SEO, UX, and even AI tools. A thriving documentation ecosystem relies on a diverse group of contributors working together to create and maintain high-quality documentation.

Review

The concept of the book is really interesting - taking documentation beyond just docs-as-code and taking a wider look at the whole documentation ecosystem. The author explains that docs happen in an ecosystem where the craft of tech writers becomes more personal, more community-driven, and much more visible. She explains that documentation is much more than an afterthought exclusive to a select team; it’s an opportunity to show a system’s inner workings, fostering a culture of openness and collaboration.

Instead of viewing documentation as a static entity, (a set of Markdown files or code snippets) it’s seen as a dynamic system where different components interact and influence each other.

The author recognizes that documentation development involves different roles and stakeholders, such as technical writers, designers, developers, product managers, technical support teams, and beyond. By adopting the “docs-as-ecosystem” term, the software development community can encourage collaboration across diverse stakeholders and facilitate the creation of high-quality documentation.

Particularly interesting was the chapter on AI, highlighting its potential benefits, challenges, and ethical considerations.

Lessons learned / Things to remember

Documentation is not just a technical writer sitting in front of a text editor. Instead, technical writing permeates throughout the whole software creation lifecycle.

The importance of feedback is another point that comes up frequently in the book. Iteration and constant improvement based on feedback is a key concept.

Another interesting lesson learned was that we often think about the UI/UX of the product(s) we document, but it is easy for the UI/UX of our docs sites to get lost in just getting content out there.

Things I already knew / Sections to skip

I was already aware of quite a lot of the concepts and details that the book included. For example, tech writers contribute to UI/UX (of the product and docs platforms), they need to know about SEO, information architecture, style guides, CI/CD pipelines, etc. If I read it again, I’d skip some of those chapters.

As far as API docs go, the author dedicates time on discussing whether the responsibility for writing the docs falls to the engineers or the technical writers. She mentions that it’s important to make sure that the docs accurately reflect the current state of the API, follow good documentation and grammar standards, and go through proper testing. Having a good working relationship with the team developing the APIs is vital for tech writers to deliver the best documentation to the users who rely on the API for their own products. Although these are practices we are following at my place of work, it’s still interesting to see them validated in this way.

While I feel that a lot of the book was aimed at people who are creating documentation in open source communities, I still think that a lot of the points it raises are applicable to non-open source projects.

The overall concept of treating documentation as a living, breathing, interactive guide rather than just a collection of static files is certainly an interesting one.

Recommended for / Not recommended for

I would recommend this book to technical writers and developers who are interested in learning about processes and co-collaboration in regards to documentation.

Having said that, perhaps some of the concepts are a little basic for more experienced technical writers and those sections can be skipped.

Ratings

  • Relevance: 4
  • Accuracy: 4
  • Clarity: 4.5
  • Engagement: 3.8
  • Usefulness: 3.5
  • Overall: 4

Resources