How-To Guides and Examples

How-to guides and examples are great ways to showcase functionalities of your tool that aren’t covered in the tutorial(s). These types of documentation are deliverable-driven: they walk users through accomplishing a specific task or reproducing a particular result. As they are intended for a more experienced audience, they require less explanation about how to generalize to a user’s own project, making them shorter and easier to write.

Your examples might highly specific, such as ‘How to design a C4-symmetric oligomer to scaffold a symmetric nickel-binding site’, where you expect users to have enough background knowledge to adapt the example to their own projects. Alternatively, they might take a more generalized form, using dummy files to demonstrate the steps needed to use a particular feature, like ‘Creating Ligand Networks Exported from Orion or FEP+’.

In this guide, we use the term “example” to refer to documentation that users can actually run, while a “how-to guide” demonstrates a feature using placeholder inputs or dummy parameters. How much explanation and structure to surround your example/how-to guide with will depend on your intended audience and the features you want to showcase.

This section covers:

• What to write your Examples/How-To Guides about
• How to make Examples/How-To Guides easy to follow
• How How-To Guides and Examples differ from tutorials

There are no templates for examples or How-To Guides in the companion GitHub repository, since their structure can vary widely. If you want to write a more structured guide, you can start with the tutorial template. On the other hand, an example might be best presented as a runnable script rather than a Markdown document.