Getting Started, Solve-a-Problem, and Arch-and-Design

This post is about creating an effective body of knowledge for helping developers succeed with your product.  When I try to size up a space in terms of technical documentation, best practices, and prescriptive guidance for a given domain, product, or technology, I use the following mental model:

image

I think of it in terms of three basic buckets:

  1. Getting Started.   This is a relatively finite space.  If you address the basic scenarios, how to install, how to get started, how to do a simple “hello world” and then provide a roadmap for learning and a roadmap for knowing the timelines and paths for the technology, you have a pretty good baseline for users to get up and running.  My two favorite developer guidance tools here are a map of the technology in terms of the key components, features, and APIs (like a “PDC Poster”) and a walk through the flow of a request (like a UML sequence diagram.)
  2. Solve-a-Problem.  This is the space in the middle and it’s infinite.  You can think of it in two big parts though: common and niche.  There is a set of common challenges that a broad set of users will face, and then there is a set of long-tail, corner-case, and niche set of challenges.  The better you solve the common problems out of the gate for the broader set of users, the more successful you can make your product.  You can find these common challenges by using people and SEO (Search Engine Optimization).  On the people-side, you can use experts and mentors in that space, to map out the common challenges.  On the SEO side, you can simply map out the demand using keyword analysis.
  3. Arch and Design.   This is another finite space.   While it might seem infinite because it’s complex, it is actually pretty finite.  You can map out this space pretty quickly for a given technology by mapping out the common deployment patterns, the application types (the canonical app archetypes), the key design patterns for common scenarios, and how to address quality attributes such as security, performance, and reliability.

While the path to mastery might be a long one, there is no reason why the path to effectiveness can’t be a short one – especially in a world of addressed “Just-in-Time Learning.”