Blog
Why Good Documentation Matters and How Diátaxis Makes It Better
Why Good Documentation Matters
Good documentation is crucial for the success of any software project. It ensures that users can effectively understand and utilize a product, reduces the need for extensive support, and helps maintain a high standard of quality. Despite its importance, many projects suffer from poor documentation, which can lead to frustration and inefficiency for both users and developers.
Common Pains for Readers of Documentation
- Difficulty Finding Information: Users often struggle to locate the specific information they need due to poor organization or unclear navigation.
- Lack of Clarity: Documentation that is unclear or overly complex can confuse users, making it hard for them to understand how to use a product effectively.
- Inconsistency: Inconsistent terminology, style, and format can lead to misunderstandings and a lack of trust in the documentation.
- Outdated Content: Documentation that is not regularly updated can provide incorrect or irrelevant information, leading to further frustration.
- Incomplete Coverage: Missing information or gaps in documentation can leave users without the guidance they need to fully utilize the product.
Common Pains for Writers of Documentation
- Unclear Objectives: Writers often struggle with understanding what type of documentation is needed and what the specific goals are for different user groups.
- Maintaining Consistency: Ensuring a consistent style and format across various documents can be challenging, especially in large projects.
- Keeping Documentation Updated: Regularly updating documentation to reflect changes in the product can be time-consuming and is often neglected.
- Balancing Detail and Brevity: Finding the right balance between providing enough detail to be helpful and keeping documentation concise can be difficult.
- User Feedback: Collecting and incorporating user feedback into documentation can be a daunting task, but it is crucial for maintaining its relevance and usefulness.
One effective approach to addressing these pains and achieving high-quality documentation is through the Diátaxis framework.
Diátaxis: A Comprehensive Approach to Documentation
Diátaxis is a structured methodology for creating and organizing documentation. This approach, derived from the Ancient Greek words διά (dia, meaning “across”) and τάξις (taxis, meaning “arrangement”), emphasizes a holistic view of documentation that ensures clarity, usability, and maintainability. Created by Daniel Procida during his work on the Django project, a popular Python web framework, Diátaxis offers a user-centered focus beneficial to both writers and readers of documentation.
Diátaxis is also known under the name Divio Documentation System. It was created and maintained by Daniel Procida when working at Divio, a company that provides cloud infrastructure management for web apps.
What I personally and specifically value about the Diátaxis approach is the user-centered focus on both the writers as well as the readers of documentation. It thus fits very well to many other methods and techniques thatare user- and/or customer-centered.
Continue reading ...Shreyas Doshi on High Agency
A recent LinkedIn post by Marty Cagan has directed my attention to an article by Shreyas Doshi on High Agency.
Shreyas discusses the concept of High Agency, an essential quality he’s observed in successful leaders. High Agency involves taking proactive steps to achieve goals without waiting for ideal conditions.
Shreyas contrasts High Agency individuals, who drive change and overcome challenges, with those lacking agency, who blame external factors for their setbacks. He emphasizes the importance of High Agency alongside talent and integrity, urging leaders to prioritize it when hiring. Shreyas provides insights into cultivating High Agency, recommending revisiting Stephen Covey’s “7 Habits of Highly Effective People” and focusing on traits like an ownership mindset and skills like creative execution.
He acknowledges the challenges but encourages readers to learn and embody High Agency for personal and professional growth.
Areas of own High Agency
From my personal experiences, I can confirm that High Agency was and still is highly relevant to advance many product-related topics.
Retrospectively, there are numerous examples that I would attribute to my own agency rather than my talent.
Here’s a list of examples from my time as product manager for ETAS EHANDBOOK:
- Killing 3 product innovation ideas without potential (e.g., an interactive model viewer) and formulating a vision for a new solution that would address real user problems (ECU software documentation) (2010)
- Piloting Scrum at ETAS for the development of a then new product (2011)
- Creating and publishing introduction and what’s new videos instead of offering paid live trainings (standard approach at ETAS at the time) to scale the rollout https://www.youtube.com/playlist?list=PLdK8AlEjocsX3lrfL0TUT24buW16oagWL
- Switching from standard PDF-based user documentation (the standard approach at ETAS at the time) to web-based online docs & tutorials https://ehandbook.etas.com/docs/
Product Quality from PM perspective
Peter Yang, currently Product Lead at Roblox who also runs a popular newsletter covering product management topics, recently had an interesting LinkedIn post on product quality that caught my eye.
After watching the video with Steve Jobs and reading Peter’s blog post, I realized that there are many aspects that I totally agree with as I had unknowingly used similar analogies when creating EHANDBOOK with my team at ETAS.
Continue reading ...New insights on strategy
Recently, a colleague shared some very interesting insights on LinkedIn about strategy development.
The post contained a video from Roger Martin A Plan Is Not a Strategy. Here’s the video by Roger Martin:
Continue reading ...Marty Cagan: Alternatives to product management & product leaders
Marty Cagan has recently published two new articles: Alternatives to Product Managers and Alternatives to Product Leaders as a reply to Brian Chesky’s new playbook.
There’s a couple of quotes that I’d like to preserve for myself as I find them extremly valuable to reflect upon my own role.
Continue reading ...On time, on budget, on spec
“On time, on budget, on spec” – three constraints that often feature prominently in job postings for project managers and product managers.
The request is understandable from a management and controlling perspective; however, it’s fraught with challenges and is often unrealistic.
It is often a reality that only two out of the three pillars—being on time, on budget, or on spec—can be fully achieved, highlighting the need for adaptability and strategic decision-making.
Continue reading ...Mastering Tactful Prioritization: Navigating Stakeholder Requests with Finesse
As a product manager or product owner responsible for software-based solutions, one of the critical challenges you face is managing stakeholder requests and prioritizing features or enhancements. Saying “no” to customer wishes, user requests, or any other stakeholder demands requires finesse and tact. While the attribution of the following quote is uncertain, its essence captures the art of tactful prioritization:
Tact is the ability to tell someone to go to hell in such a way that they look forward to the trip.
– Winston Churchill
Let’s explore how this concept of tact applies to the realm of product management and handling stakeholder expectations.
Continue reading ...What makes a product manager a good product manager
I have asked ChatGPT the question what makes a product manager a good product manager.
Here’s what ChatGPT provided as an answer. From my perspective, this is a very good description.
A good product manager possesses a combination of skills, knowledge, and qualities that enable them to effectively lead and manage the product development process. Here are some key factors that contribute to making a product manager good at their role:
Continue reading ...The JTBD market definition canvas
Tony Ulwick has written an interesting article on The JTBD market definition canvas. In the article, he also provides a very helpful way for how to define a market.
TL;DR
Continue reading ...A market is defined as a group of people + the job that they are trying to get done.
Product vs. Feature Teams
Today, I came across an interesting article by Marty Cagan on the difference between empowered product teams and feature teams.
Continue reading ...What does a product manager do?
I got a new follower on Twitter today (@NilsDavis), and it turns out he is he is a product management veteran himself and runs a series of interesting resources (website, podcast, etc.).
I have just started browsing through his website, but already like what I have found.
Especially the introduction to “What does a product manager do?” is a good read for anyone not into product management yet or who is struggeling on interpreting this role.
Continue reading ...Why I started this page
TL;DR
The three main reasons why I started this site beginning of 2023 are:
- There are too many bad engineering tools
- Good products are often sold under value
- The missing link: value-centric product development and pricing
subscribe via RSS