Doc project tenets

Tenets are guiding project principles; they outline and frame design thinking.

Here are the ones I generally start with.

Docs are features

Many teams treat docs as afterthoughts. Like good software, good docs require design, forethought, and planning.

Effective docs follow the product lifecycle: design, implementation, review, and maintenance.

Treat doc reviews as seriously as code reviews. Reviewers need to be proactive and timely in their feedback.

Feedback must be specific, clear, and actionable.

Docs solve problems

Good docs help people solve problems.

Before starting an article, identify the audience and the problem.

This defines the intent:

• “As a developer, I want to back up my database.”

• “As a new customer, I want to update my profile.”

• “As an admin, I need to limit access.”

Like feedback, intent must be specific, clear, and actionable.

The article’s complete when it meets the intent. Everything else is extra (and probably goes elsewhere).

When you review an article, test it against the intent.

Solve first; explain later

Most people are in a hurry; they’re trying to answer a specific question.

Give them the answer. Let them decide what to do next.

Details, analysis, and architecture come later.

When planning docs, remember “Breadth, then depth.”

Work priorities in descending order. Finish what you can with what you have.

Cover basics first and then go deeper. Balance resources, priorities, and feedback.

When you do focus on specifics, start with things relevant to many users, rather than a few.

Write for modern audience

We have short attention spans and too many distractions. We tend to scan for relevance before diving deep. (Think tl;dr for, well, everything.)

This means:

• Design for scanning. Use simple sentences, short paragraphs, and lots of whitespace.

• Be brief. Be clear. Save details for later.

• Use everyday language rather than industry jargon.

  If you must use jargon, define it–especially TLAs (three-letter acronyms) and abbrs (abbreviations).

• Use informal language when it’s common.

  Example: app instead of application, info instead of information.

  When trying to decide between formal vs. casual language, choose business casual.

• Don’t assume readers have the same context or background knowledge.

• Show empathy: be direct when things are not ideal. At the very least, don’t be a jerk.

Docs cannot teach everything

Docs help people learn the basics and become self-sufficient.

It’s tempting to document every behavior and error condition. Yet, too much detail can overwhelm.

Consider practical limits and diminishing returns.

The more you write, the more you have to maintain.

Start with the 80/20 rule. Let feedback and metrics inform updates.

Publish, then perfect

Unpublished docs help no one.

Docs don’t need to be perfect to publish. You can always push an update.

Figure out what you can do with what you have. Do it and then iterate.

Mistakes are OK. Accept, learn, and move on.

It’s OK to focus

You don’t have to accept (or use) every good idea.

Accept feedback and contributions openly; use those that serve the intent.

If something doesn’t fit, throw it in the backlog and file a follow-up ticket.

Actively maintain, review, and triage your backlog. Make time for quality sprints.

Log and prioritize all requests. Work date-sensitive items in descending priority order.

More about tenets

Tenets are part of the Amazon design process. They answer questions that aren’t otherwise addressed by your project docs.

At Amazon, every project is expected to feature tenets prominently. (Some projects post tenets publically.)

By tradition, tenets are introduced the subtitle “Unless you can think of better ones.” This reminds people that tenets can, should, and do change as projects evolve.

I use tenets to:

• Set expectations
• Outline direction
• Enable conversation

These tenets are part of (nearly) every project I work on. (I don’t always tell people about them.)

Unless you can think of better ones…