User Guides
User guides are a critical resource that accompany any product. But to be effective, they need to be concise, well-organized, and easy to follow. In practice, this means each topic needs to explain its purpose, contain only the necessary wording to get the information across, and laid out in a consumable format, ideally with rich formatting and lots of diagrams to avoid the dreaded wall of text.
I’ve helped many companies – both in tech and outside of tech – develop effective user guides. I work with your SMEs when available and also use your product to capture the most important details.
Below are some samples of a user guide I developed for Octave – an IoT solution from Sierra Wireless for managing a fleet of edge devices.
The process involved working with the SMEs, the web dashboard, and multiple edge devices. Using these resources, I developed an effective information architecture following my preferred pattern of introductory topics, getting started/quick starts, and tutorials, followed by conceptual topics and reference materials. This organization helps get users up and running quickly before they delve into more advanced topics. The ever-present table of contents and breadcrumbs, also help the user understand where they are in the docs at all times.
Key Benefits of Good User Guides
- Reduce support calls
- Help users evaluate your product
|  |
 |  |
Developer Documentation
I have years of software engineering and development experience which spans business apps to multiple smash hit video game titles.
I leverage this experience on many technical projects where clients need an extra resource to develop, test, and validate documentation which helps developers find success. My work is centred around the developer’s journey – a key aspect of my Developer Relations consulting, where documentation often serves as a key touchpoint in helping developers decide if they’ll adopt a product or API.
My developer-oriented technical writing projects generally span three areas:
Developer Guides
Developer guides must help developers find success with your product or service, and supplement your API and/or SDK reference guides when applicable. Working directly with your SMEs, product, and APIs, I bring an outside perspective, from the point of view of your target developer audience, to create concise, succinct documentation.
Similar to user guides, my preferred information architecture follows the pattern of introductory topics, getting started/quick starts, and tutorials, followed by conceptual topics and reference materials. My work takes into account that each developer is at a different phase of their journey, and they can land on a given topic from a variety sources, be it a Google or AI chat search, a direct URL from a colleague, etc.
I ensure each topic starts with an explanation of its purpose, and what the developer will learn from it, while making effective use of hyperlinks to related information. Along with a well-designed information architecture, and ever-present table of contents, my documentation ensures developers can always find what they need, and the right level of detail.
Below are some examples of developer guides I worked on for Payrix, a referrer payment API by Worldpay.
 |  |
API and SDK Reference Guides
API and SDK reference guides play a crucial role in describing endpoints / functions, along with their parameters and return values. However, many companies get them wrong.
Simply put, many guides lack details because the developers either didn’t have the time or incentive to write or update the docs, or they’re too close to the code and assume the target audience only needs a limited level of detail. One of the most telling signs is a lack of parameter descriptions (e.g., the description for Get /X is “Returns x”). In addition, many companies who use code-generation tools for auto-generated code, falsely assume that just because the docs are being created and handled along with the code – nowadays referred to as docs as code – that somehow this automatically results in good documentation.
Companies often bring me in to correct this. I work closely with the SMEs, APIs, and SDKs actually trying them out from the perspective of the target developer. Experimentation can range from invoking REST API endpoints in Postman, to building projects in Visual Studio. I then work to uncover all parameter descriptions, function side effects, dependencies, and any other issues I come across, and ensure they’re distilled into effective developer resources. This also ties into my code sample work.
Below is an example of an endpoint that I worked on Worldpay’s REST API:
Code Samples
I develop in many languages, some of which include C/C++, Java/JavaScript, .NET/C#, Python, and REST APIs. I’ve worked on everything from Windows apps to embedded systems like video game consoles and Android Wear devices, and web apps using REST APIs. I’m adept at object-oriented design and design patterns, and have built many system architectures over the years.
As a developer by trade, I know the importance of good code samples, especially when it comes to building hello world examples for quickstarts. In fact, code samples are often the first resource developers will look at, before they refer to other documentation for additional details.
Good code samples need to stand on their own so developers can easily copy and try them out. This means including or documenting any dependencies, adding explanatory comments, focusing just on the task at hand, and keeping them up to date. Unfortunately, many companies get this wrong. Their samples often get out of date as APIs change, they don’t include the necessary details that enable a developer to build it, and/or they don’t show the write level of detail.
Companies rely on my software engineering background to correct this. I work closely with the SMEs, APIs, and SDKs from the perspective of the target developer, to uncover the right level of details developers need to successfully invoke functions and endpoints.
When developing code samples, I work alongside dev teams directly with their content resources including documentation systems, Markdown files in GitHub repos, OpenAPI specification files, etc. Contact me today to discuss how I can augment your team to create effective code samples for your developer audience.