Documentation is a tough sell to software engineers. We want to invent amazing features and write code, and when we finish doing that, we want to do it some more. We don’t want to take the time to sit down and actually describe what we’ve done. But if we don’t, how is anyone else — customers, colleagues, future colleagues, even our future selves — going to appreciate and understand our amazing accomplishments? Because we’re the direct source of the amazingness, no one else knows the details of what we’ve accomplished as well as we do. So why not share the wealth?
The four Credit Karma values can guide us to an understanding of how and why we should think of documentation as a crucial activity in our role as engineers.
The Credit Karma values
Credit Karma has adopted the following four values as core to our beliefs of how we can best work together — as coworkers, partners and members — toward our shared mission of making financial progress accessible to everyone.
- Ownership
- We accept personal accountability for our work and drive projects to completion.
- We clarify ownership, and if there is no owner, we step up and own it.
- We enable ownership by granting decision authority and providing the tools to effect change.
- Empathy
- We listen before we react.
- We always assume positive intent.
- We actively seek to find common ground.
- Helpfulness
- Asking for help is seen as a sign of strength.
- We help each other grow by giving and receiving feedback.
- We make time to help others succeed.
- Progress
- We align on what progress means, how to measure it and our shared goal.
- We break big milestones into small pieces so that we can learn faster and move faster.
- We have a bias toward action: We go for quick wins, keep iterating and keep trying.
We didn’t start with these four; we experimented, refined, and iterated toward the core four values over the course of about 10 months. There was much discussion and feedback from the organization during this time.
Applying the four values to documentation
These values nicely support documenting your software, whether it’s an architecture, a process or a code module.
- Ownership
- You are a subject matter expert.
- You are a capable writer.
- Your knowledge is valuable and worth sharing.
- Empathy
- Put yourself in the position of someone seeking information or understanding.
- Understand how it feels to be confused about a process or stymied by a missing piece of information.
- Realize it’s worth the effort if you could reduce or eliminate that frustration for other people. One person can leverage their knowledge for many people.
- Helpfulness
- Share your knowledge in a structured, coherent way.
- Increase efficiency by separating the information signal from the noise.
- Reach out and support interested people throughout the organization.
- Progress
- We can all move faster when we can locate and access the information we need.
- Written knowledge has value only if it’s correct and current.
- Keeping information current is as important as writing it down in the first place.
What to document?
At a high level, software is the result of architectural and design decisions. The architecture represents the significant decisions — those that will be difficult to change; the design is everything else.
Here are some examples of significant decisions, in three broad classes of requirements:
- Functional Requirements — business rules, time to market, transactionality, authentication and authorization, legal or regulatory compliance
- Architectural Requirements — client/server, mobile, microservices, programming language, front-end framework, back-end database, API framework, mobile framework
- Non-Functional Requirements — scalability, performance, availability, security, capacity, reliability, maintainability, recoverability
All of these examples represent decisions that will be difficult to change after they are implemented. So they should be treated with significantly more care than your choice of typeface or theme colors. This includes documenting your decisions in detail, so the entire team knows what they are and how they were made.
How to document?
As a developer, you’re typically concerned with two main types of documentation:
- Product Documentation — this is targeted at the users of your software
- Why — what business requirements the software claims to meet
- What — the user-visible components and their relationships
- How — instructions on how to use the software
- Project Documentation — this is institutional memory, targeted at your colleagues and your future self
- Why — maintain high levels of quality and consistency, explain your reasoning behind the architecture and design, and resolve disagreements
- What — know what you’re working on by providing detailed descriptions of the component internals and how they fit together
- How — ensure that everyone consistently implements features and fixes by describing the solutions and technology implementing the software
Key Takeaways
Documentation is difficult to create and even more difficult to keep current and relevant. To paraphrase Mark Twain, “Documentation is what everyone wants to read, but nobody wants to write.”
- Take ownership of your documentation
- Keep your readers in mind
- Share your knowledge
- Publish early and often, and keep it current
Be considerate of your colleagues and your future self: think of writing documentation — and keeping it current — as a valuable, ongoing part of your job.
Portions of this article are reproduced from Shared Values Produce Better Work.
