The Art Of Technical Documentation

Product managers love their jobs. There's nothing like powering through a project with a team of brilliant minds to come out and know you've all made a difference.

Most time spent being a PM isn't that moment. Much of our time goes in to thinking through complex problems, but the vast majority of our efforts are spent turning ideas into things that work. It's not so much our ideas that consume our time, rather the ability to explain those ideas to entire teams of people in excruciating detail.

The best way to learn is to teach, and the finest way to define a full product is by dictating it to others. Explanation is an art form.

These are some of the most common ways of putting prattle into practice:

Functional Specifications

Specs are the monoliths of documentation stemming back to the waterfall days. Functional specs routinely range from 100-300 pages of requirements in the form of annotated designs, leaving no stone unturned.

Authoring effective specs takes an analytical mindset and a lot of patience - neither of which are particularly common traits. A good spec should have all edge cases premeditate. The purpose of these documents is to contain the answers to any questions developers might have before they get the chance to ask them.

Unsurprisingly developers rarely read every detail of a spec, but rather skim to the parts they find to be important. Take this into consideration before investing weeks into making the 'perfect spec document.'

Startups rarely employ this type of documentation today.

When to use specs:

Waterfall Development. This is a no-brainer; requirements are one of the many steps in a traditional waterfall process.

Eliminating Edge Cases. Products which cannot launch as an unevolved MVP need to ensure that every scenario is accounted for, as iteration is not a viable strategy for some sectors (think finance).

Offshore Teams. Teams which operate on different hours or do not speak English as a first language will need far more detail to remain productive. Specs often contain redundant detail to avoid the alternative disaster of having something built incorrectly.

Thinking to the Future. Large companies will turn over employees while their products remain the same. Future employees will need to know how the current systems work.

Visibility to Stakeholders. Money feels better spent when investments come with a 10 pound printed document made from sweat and tears.

Gantt Charts

Gantt charts are the standard method of timeline tracking which needs no introduction.

The format for Gantt charts is universal, but the methods for up keeping and adjusting dates during the project differ between organizations. Gantt charts are just as often abandoned as they are constantly groomed as dates shift.

When to use Gantt charts:

Setting Expectations. Even if the chart itself is forgotten after day 1, the exercise of creating this timeline provides a ballpark en date, as well as an explanation of why.

Managing Missed Deadlines. If maintained, Gantt charts can serve as the authority of accountability for clients and stakeholders. This creates an understanding of urgency when feedback takes a little longer than usual.

The Ticking Clock. Some teams go so far as to print a large Gantt chart to be displayed on the wall to start a project, which then becomes the law of the land.

Issue Trackers

Issue trackers such as Trello or JIRA are utilized by nearly all tech organizations (hopefully). Issue trackers can capture the same detail as functional specs, but additionally track time and progress. In the leanest settings, issue trackers replace both functional specs and Gantt charts.

Issue trackers should be the meat and potatoes of any PM's arsenal. These tools focus on the completion of smaller tasks, lending themselves well to the natural reward system hardwired into the human brain.

Unlike classic documentation, issues can be queried, filtered, assigned, completed, and reflect relationships between tasks at hand. This makes issue trackers more powerful than traditional documentation.

When to use Issue Trackers:

• Almost Always. Issues can even be linked to functional specs to get the best of both worlds. These PM tools are a clear step forward in how we think about building software.

Logic Flows

Projects which lack emphasis on interface are sometimes better off with none of the above. When building products such as complex back-end integrations, or SMS text message flows, the visualization of logic takes precedence over user stories or annotated designs.

When to use Logic flows:

Backend Service Integrations. Large scale products consuming multiple third party services are served best by having these pieces displayed visually.

Products without UI. Without a traditional interface, logic flows are essentially visual user stories.

Explaining Complexity Products which are mostly straightforward will sometimes have one or two features complicated enough to warrant diagrams explaining these isolated pieces.

Sitemaps

Visual sitemaps are typically supplementary documentation for content-heavy projects, where taxonomy is of higher importance than functionality.

When to use Sitemaps:

Enterprise-Scale Rehaul. Large products experiencing a hierarchy shakeup will have high needs for a visual representation of the new site structure.

eCommerce. Great example of a product type with very little page differentiation, but complex taxonomies.

Bottom-up Management. While the age gap in tech still exists, it is important to present information to senior executives in a clear visual manner.

Shooting from the Hip

Besides the basics, there will always be the unorthodox methods of communication we're all guilty of. Google docs, slack chats, and obscene multi-colored email threads, to name a few.

These simple tools may very well be enough to fit the needs of your team. Unfortunately, these are also the kinds of important information that gets lost on the event of employee turnover.

The Full Arsenal

Rarely should you ever encounter a project that utilizes each and every one of these types of documentation. If this is the case, it may be worth considering that some things can be removed for simplicity.

Documentation is a necessity to projects but enemies of the human mind. Nobody likes reading your requirements any more than you like writing them (don't act like you rush out of bed to write hundreds of JIRA tickets every morning).

Simplicity is key. Visuals communicate ideas faster and more effectively than words. Be brief yet concise. Informative but beautiful. Analytical but human.

Nobody wants to spend weeks writing documents that no soul will ever read. Trust me, I've been there.