Many tech manuals explain concepts at a high-level without teaching a reader how to accomplish a task, or use official, deterministic documentation that assumes a reader already knows half of the concepts. This section fills that gap, providing seekers of practical, step by step instructions with explicit task goals.

Guides in Practice

There is a distinction between having a complete understanding of a concept and being able to execute it. Many people are able to define what a merge conflict or version control is, but have never done it in practice. Knowing about an AI coding assistant and actually implementing one in a workflow that saves time and avoids unnecessary review work is a big distinction. The void between knowledge and experience is where most people seem to get stuck, which is what closing that gap seeks to provide.

It’s also where the true deviation from the competition is, authentic differentiators that are clear only with deep tests. Many people are able to explain what a local development environment is, but very few people are actually able to write guides on how to accomplish setting one up and suffer through all of the failures, dependency issues, and the infamous “it works on my machine” section of the guide.

What makes a good practical guide

Useful how-to guides are almost always specific. Many how-to guides will say “install the necessary dependencies”, but useful how-to guides will say which dependency, in what order, and will explain what to do if the install process dies. Being vague about the how-to guide is almost useless because chances are it will be helpful to someone. A how-to guide in this context is about helping people finish a task, rather than walking them through the task itself.

Being specific and leaving out the things you assume is also useful. Saying how to set up a local development environment is very different if someone is doing it for the first time versus if someone has set up part of the tools before. Being clear about the starting point will save people from unnecessarily doing steps that do not apply to them.

A bigger chunk of the guides in this field must begin to account for how AI tools actually fit into the real-world day-to-day process. It means showing what a coding assistant is good for in the real world and where a coding assistant needs guidance, for instance, when it comes to understanding the context of a code snippet and the reason(s) behind its construction. A coding assistant may be capable of understanding that a function call is missing, but a coding assistant won’t (and never will) know why it is missing. The real utility of this content is that it posits realistic scenarios of a coding assistant in action, including situations where the coding assistant is wrong. This is a more honest representation of users’ actual expectations of the product.

Writing for different starting points

Not everyone reading a step-by-step guide is in the same place. Following the same steps for all does not help anyone. One example: a beginner who’s never used a terminal needs different instruction steps for learning basic commands than a seasoned coder who’s just about to start using a new tool. It’s better to identify the audience of a self-directed guide and lead with who it’s intended for: beginner, intermediate or advanced. Doing so allows readers to determine quickly if their needs can be fulfilled by the guide or if they should seek out something more introductory or advanced.

Time is important for everyone, and the time that your potential reader invests on your guide will determine if they continue to support your effort by reading more. Losing their trust by explaining things they already know before getting to the valuable content will make them disengage and will negate all your good efforts.

Managing guides for time relevance

Tooling changes frequently and a guide written a little over a year ago can already be pointing out a command that no longer exists or an interface that has changed. Most content needs to be updated less frequently, but practical guides need it more often. For practical guides, it’s better to disclose when the guide was last verified to be updated, rather than allowing steps to remain that no longer work.

What you can see here

This section will develop incrementally instead of arriving fully formed. The initial offerings are setting up your development environment, hands on with Git, and applied use of AI-powered coding tools. Additional resources will be added as the tooling folks are actually asking about changes.

The linked guides take you through each of these in detail.