Writing an Overview

Included here are the questions that you will also find in the overview.md template in the companion repo for this playbook. Here, we’ve expanded on these questions to give you more to explore when you’re thinking about what to include in your overview. Not every question will be relevant for your project, and there maybe other information you would like to include in your overview that is not mentioned here.

Writing Tip: If you get stuck, try describing your project to a friend/colleague who is a fairly good representation of a user of your tool. What would you say? What questions do they have as you’re explaining it?

1- or 2-sentence summary of what the tool does:

This can be taken from your README.

Why are people interested in this tool?

• What problems does this tool solve?
• What questions can this tool help answer?
• What does this tool produce?
• Is this tool meant to be part of a larger workflow?

Background information

• What information is crucial to understanding what the tool does, but a typical user may not know?
  • Example: There are many ML tools for protein design, but protein designers do not necessarily know much about ML methods. What do they need to know to effectively use your tool?
• Are there external resources that users should go to if they would like to learn more?

What knowledge are you assuming the typical user knows?

• Are you assuming they already have experience with a related tool/application/project?
  • You don’t necessarily need to explain these topics, but linking to external resources could be helpful.
• Are there publications related to this tool?

Where to start?

• If you were talking to a new user, where would you tell them to go next? The installation guide(s)? The basic use case tutorial?