What makes good developer content?
The best content for a developer is a tool that just works without reading content.
Now, this is dependent on the category of product, the type of developer, and the use case.
The point, however, is that content or docs should not be the bandage for a product that isn't as intuitive as possible.
Is it possible to eliminate the entire need for any documentation at all?
Probably pretty difficult. But with AI, a developer should be able to query any "how to's" without needing to read the document directly.
Does this mean there is no need for documentation?
No. Documentation about context can be very helpful for developers if the tool or solution you are providing needs this.
So if you're determining your developer content, you need to identify your goals.
Here is a simple way to frame these goals:
- Awareness
- Activation
- Build and Ship
- Maintain
- Contribute
If your primary goal is Awareness, meaning, you need content to attract new developers, documentation may not be the right point of focus.
Developers don't typically look for documentation if they don't know what the product is or why they need it.
Documentation can help with Activation on-wards. And the less the better.
The other thing to consider is whether "content" always means a tutorial.
These can, and we have seen that the right tutorials in the right set of problems can drive awareness and activation.
But, useful content can also include things like:
- Postman importable sets
- Walk-throughs in the CLI
- Extension for VS Code
Thinking through content is best if product-led: what is most needed to achieve the most critical metric in the developer journey.
Are quests and tutorials good content?
Recently, I tried to go through the AO testnet Quests.
On the one-hand, quests do have the potential to guide users through the key structures and concepts.
AO wants to convey the benefit of using decentralized compute processes to send messages to each other to achieve parallel computation.
The quests were designed to help developers to slowly add new features.
In theory, it seemed reasonable.
Here are some of the challenges for quests and any kind of tutorial: identifying the key concepts so that a developer can get up and running on their own projects as soon as possible.
The way the quests were on AO were some basic capabilities and then jumped quickly to a full-on project: building a token.
Nothing wrong with these concepts. On the one hand, a goal should be to get the developer to something that they can use or that is cool. Ideally it should be something they could then build upon in their own way.
On the other hand, the goal should be to get developers off on their own projects.
The right balance is difficult. The more "boilerplate" that the quest or tutorial needs to include to get something useful, the cooler the output is, but the harder it will be to understand the basics to get up and running.
On the other hand, something too simple just leaves people at the "hello world" level.
The right content finds this balance, and it likely can only come from feedback and iteration....talking to the developers you most want, looking at challenges they have in tutorials, etc.
How to construct a tutorial
The best tutorial should have two basic elements: 1) it helps the developer to get to what they really want; 2) it should do so in the shortest, more generic, way possible; 3) have roadmaps or levers to progressively increase the specificity and customizability.
One example, for example, are the tutorials to build a subgraph.
What is it that they want to do (a goal independent of the tool).
In this case, the goal is to query for indexed events from their smart contract.
The goal, itself, is very specific as a goal: how does the developer query indexed events?
In this case, the tool now needs to show a clean, understandable path to get there. This is the goal of the tutorial.
However, there's a generalizability to this: it's not limited to a "hello world" smart contract, but can be appropriated for any smart contract.
To do this, the tutorial has four straight forward steps with a cut and paste for the command line.
(put examples here)
At the end of this, the developer is able to get what they want (their core job to be done): an API which lets them query the tutorial's smart contract.
The "hello world" in this instance is generalizable to what the developer really wants to do. All they need to do at this point is change the example contract with their own and they can repurpose the tutorial.
Extending and Customizing
Once the basic building block is established, a developer may want to go beyond the default settings. Here is where both the documentation and the product may want to ensure the best developer experience.