I am a big fan of Steven Covey’s Begin with the end in mind from his book The 7 Habits of Highly Effective People. For a technical content guy like me the key question is How the technical content should look when it hits the Internet? Think of a TOC (table of contents) or even in terms of IA (information architecture). Based on my experience working with customers there are three key questions the technical content needs to answer:
- What’s in the bag?
- When to use?
- How to make it work and keep it working?
Using this simple frame this is how I see the End in Mind for developer audience.
What’s in the bag?
This part should help the customer to quickly understand what’s actually being “sold”. Imagine you pick a product from the shelf. It usually lists what’s inside. When it doesn’t the customer prone to buying wrong product. These are the key parts that needs to be covered for developer audience:
- Features. List and describe available product features.
- API reference. List and describe available API.
When to use it?
Now that the customer understands what’s inside he’s wondering if this is really what he needs. Will this product or technology help him solve his real world problems? This part should help him to make this decision. Otherwise he is left to his own devices to figure this out and usually it takes time using trial and error approach very few can afford and even fewer actually love doing so.
- Scenarios and solutions. Show how set of How-To’s can solve specific scenario.
How to make it work and keep it working?
At this point the customer knows what’s offered and how it can solve his real world problems. Now his natural ask is “Show me how.” In this section the customer is shown how to quickly get started, then how to make features work and how to keep them working. Also, he is shown how to recover if things go wrong and how to recover from the mess.
- Getting started. List prerequisites and offer quick walk through for what it takes to get going, usually using Hello World approach.
- Step-By-Step How-To’s. Show how to make features work.
- Security and Performance guidelines. Show how to defend from attacks or how to sustain higher load.
- Troubleshooting cheat sheets and error codes. Show how to quickly recover when it hits the fan.
Tests for Success
This is it for the high level of the End In Mind of the information architecture for developers content I was using for the last two years. Was it successful? Here are few remarks from the those who used it in the field, it should give some hints:
- “It looks amazing !!! A. It includes lots if knowledge (easy to find the knowledge you need). B. It provides practical info how to implement the scenario.”, Security MVP
- “[I like] the consistent approach used in each of using minimal amount of text and easy to follow model to describe scenario and solution” , PRINCIPAL Architect.
- “Useful: Absolutely. Usable: Yes. The method of presentation: short scenario description, consistent diagrams and brief highlights etc. is ideal for quick consumption.”, Sr. ARCHITECT, MCS
image by striatic