Skip to main content
Version: v2 ⚡

Writing Docs

Please feel free to point out issues with this documentation or, if you can't find the right repo, issues with the tools themselves. (The more feedback the better!). If you want to propose some new language for the documentation, you can make those changes by clicking the "Edit this page" link at the bottom of any page and submit a pull request!

Intro​

This document is meant to be a guide for OpenFn’s documentation. Remember the goal is to treat “docs like code” and to create a docs portal that makes using OpenFn's tools a fairly self-service experience. Feel free to contribute to this document.

What are docs​

When we say docs, we mean streamlined, tightly phrased, and fast-moving information that helps citizen integrators using OpenFn understand the platform’s complex application interfaces. What does treating docs like code mean? Store the doc source files in a version control system. Build the doc artifacts automatically. Ensure that a trusted set of reviewers meticulously reviews the docs. Publish the artifacts without much human intervention.

(Source: Anne Gentle’s book Docs Like Code.)

Goals for these docs​

Promote collaboration​

Collaborate with contributors efficiently by keeping docs in the same system as code with deliverables generated from source files.

Get long tail contributions​

Split deliverables into parts that encourage small but mighty contributions. One person no longer needs to own an entire deliverable of documentation.

Track doc bugs like code bugs​

When you fix a doc bug, you reference that bug in the commit message to help reviewers judge whether the doc fix solves the stated problem.

Get prompt and good quality reviews from team members​

Trust team members to value docs, ensure technical accuracy and consistency, respect end users’ needs, and advocate for the best doc deliverables for consumers.

Make beautiful docs​

Design is important. Create beautiful and modern looking docs.

Use developer tools and workflows​

Automate the process as much as possible, so we can focus on content creation.