Writing Documentation

You’ve created some new code for the IDAES project. Excellent! But now comes the difficult task of documenting what you’ve created. While you may already have written verbose docstrings, added comments throughout your code, and tried to name the variables and functions in ways that just make sense, we want our code to be even more accessible to our audience. Not everyone is ready or willing to jump down to the module level and learn by getting their hands deep in the code. This is where writing documentation comes in handy.

---

Table of Contents

• Guiding Questions for Getting Started
  • What is the reader’s expected familiarity with the tools?
  • What is the goal of this documentation? (Applying the Diataxis Framework)
• Writing Documentation
  • Introducing your content
    • Why is your documentation useful?
    • What makes this topic different from other pages in the documentation?
    • What background information is needed?
  • Adding your page to the index
    • Adding your page to index page Contents Table
    • Adding your page to subdirectory index pages
  • Make your documentation enjoyable to read

---

Guiding Questions for Getting Started

What is the reader’s expected familiarity with the tools?

When creating documentation, think about the background knowledge of the users you expect will be reading this documentation. By keeping this in mind, we can present information in a manner that is appropriate for our assumed level of reader knowledge.

• What level of familiarity do they have with the IDAES platform?
• Is this documentation meant for someone with a deep knowledge of our tools or someone who may be less familiar?

What is the goal of this documentation? (aka Applying the Diataxis Framework)

• To walk someone through a task (aka Tutorial)

  • This leads the user step by step from start to finish of a defined process resulting in a successful outcome, showing them the exact inputs and expected outputs from these actions. This focuses on learning a skill rather than explaining a process.
    • IDAES example: Advanced User Installation
    • How to write a Tutorial

• To direct them as to how to do a task (aka How-To Guide)

  • This describes a series of steps from a defined starting point, which does not have to be square one (unlike a tutorial). This shows the user the steps taken, without requiring the same explicit & exact inputs and outputs that are required of a tutorial. A How-To Guide should be modular enough for the user to modify the content to fit their needs.
    • IDAES example: General Workflow
    • How to write a How-To Guide

• To describe what a tool does and how it is operated (aka Reference Guide)

  • This is a technical description of how a tool or system functions and how it can be used. This is our most common type of documentation, describing the inputs, outputs, and usage of APIs, classes, and functions. Reference guides should be easy for readers to consult. They shouldn’t be required or expected to read all of it, only to get what they need and continue on.
    • IDAES example: Physical Property Package Classes
    • How to write a Reference Guide

• To answer the “Why?” & explain from a big picture perspective (aka Explanation)

  • This is an understanding-oriented description that clarifies and illuminates a topic through discussion. While other Diataxis models are concerned with what the user is doing or what the machinery is doing, explanations focus on a “Why?” question, expanding a reader's understanding of a topic not through action but thorough discussion of the big picture, the history, the choices and possibilities, and the reasons and justifications on why something was designed the way it is.
    • How to write an Explaination

Read more about the Diataxis Framework.

Writing your docs

⚠️ Always run build.py on your docs before submitting & please run your text through a spell checker to look for any spelling errors.

Introducing your content

While it may be obvious to you why the documentation page you’re creating is relevant (my code is revolutionary and everyone should know it!), it’s important to make sure that our readers are on the same page; We need to bring the reader up to speed as to where they are in our documentation and why they should keep reading.

With the targeted goal and audience in mind and your understanding of the best Diataxis model under your belt, create an introduction that will get the reader acclimated to this section of the documentation by answering the following questions.

Why is your documentation useful?

Break down what the goal of the documentation is and what benefit the reader will gain from reading it. “This page will explain how to do _____, which can be used in these ways…”

What makes this topic different from other pages in the documentation?

There are many interconnected pages on IDAES that may seem similar to a reader. In your introduction, make sure to provide the user with enough specific information to discern the goals of the documentation and how it differs from other similar or related pages.

What background information is needed?

Make clear what background knowledge is needed to understand a new piece of documentation. Highlight (and link to) any concepts the documentation with which the user is assumed to be familiar. Learn more about creating cross-reference links in Sphinx here.

Adding your page to the index

Adding your page to index page Contents Table

If you want your new documentation directly listed on the IDAES index page, you can add a doc reference link to the Contents table. Based on which Diataxis model you created your documentation under, you can add your item to the table cell using the following sphinx code as a framework:

    * :doc:`DOCS TITLE <REFERENCE/LINK/WITHIN/DOCS>`

Please use the :doc: reference type.

⚠️ Unlike the Sphinx Table of Contents, items are not automatically added to the Contents Table on the index page. They must be added manually

Adding your page to subdirectory index pages

If you want your documentation listed on a topic index page, such as the Reference Guides Index page or the Flow Sheet Models Index page, open the .rst file for that index page and add your page to the toctree.

Make your documentation enjoyable to read

Don’t try to DRY!

ARID! Accept some Repetition In Documentation!

Make content Skimmable

Use headers to your advantage. Use bullets, use bolded text, and use verbose text to explain hyperlinks (not “click here” or “this page”).