DEV Community: Doctave

Continuous documentation: publishing docs early and often

Nik Begley — Mon, 05 Feb 2024 11:18:01 +0000

One of the key pillars of docs-as-code is releasing changes via CI/CD. Just as how software is often released continuously, we can keep our documentation up to date as the product changes.

This lets us achieve continuous documentation: instead of large bulk releases, we can incrementally improve our documentation, as we make changes to our product.

Let's dive into how continuous documentation is implemented in practice.

Making it easy to make changes

The key to continuous documentation is making it easy to contribute to documentation.

We want to lower the barrier to making changes, and empower contributors to make the docs better. Let's see how!

Smaller, iterative changes

The bigger the change, the harder it is to make. Everyone who has worked in the technology industry has seen large project spiral out of control, missing deadlines, and seemingly never ending.

Fast-moving teams get around this problem by splitting work into smaller chunks. Instead of a large monolithic release, preferring smaller, iterative changes that are easier to manage. Small changes are easier to review, have less risk, and can be shipped with fewer checks in place.

Releasing docs with code

It makes sense to update your product and documentation at the same time. Documentation should be in your "definition of done": a hard requirement for a feature to be released.

A Git monorepo, it's natural to even have code and documentation changes in the same branch or pull-request. Engineers and technical writers can work in the same branch, and eventually merge and deploy the code and documentation in tandem.

This is what we do at Doctave. We use a monorepo with a dedicated /docs folder. Every customer-facing feature will have documentation changes included, and get reviewed as part of the same pull-request on GitHub.

A multi-repository setup requires some more coordination. but the same principles apply. Every feature change should have a corresponding change in the documentation repository.

Empowering contributors

Documentation is the responsibility of the whole product team. We want to foster a culture where everyone is welcome to contribute by either writing or reviewing documentation.

Companies like Google, Twitter, and Spotify put a lot of effort into building a culture of documentation. We also see this at many of our customers: reviews are done not just by technical writers, but engineers and product managers responsible for the implementation of a feature.

Automate, automate, automate

Automation means your process is repeatable and, most importantly, transparent. You don't want to be bottlenecked by that one person who knows how to copy your final artifacts to the production server.

Instead, when changes are merged, they should automatically be deployed without human intervention.

If you are worried about quality issues, you can catch lots of common issues with tools like linters like Vale. They will check your content for spelling issues or unwanted phrases. This lessens some of the burden on the manual reviewer.

Implementing continuous documentation

Let's talk tactically: how do we implement continuous documentation in practice?

CI/CD integration

CI/CD plays an important part in continuous documentation since it's the engine automating everything.

The exact way you should implement CI/CD depends on your repository setup and choice of tools. At minimum, you need to be triggering automatic deployments whenever new changes are merged in your main branch.

To give a more complex example, we have an example in our documentation about how to integrate Doctave to your CI/CD pipeline in GitHub Actions.

The way it works is:

Any time there is a pull request, or we've merged changes into the main branch,
Check if there are changes to the docs/ subfolder,
If so, send the docs to Doctave

We then have versioning rules set up in Doctave that update the public-facing documentation when the main branch is updated. Else, we just get an isolated preview environment that we can use in our review process.

It's simple, and works great!

Building a culture of documentation

We want to empower contributors by building a culture of documentation. Instead of technical writers being solely responsible for docs, developers should feel welcome to write documentation for the features they are working on, and product managers should be considering how documentation fits into the overall product.

We have found there are three key steps to doing this:

Standardize your process and tools: Teach everyone in your team how your documentation is updated
Make documentation an expectation: No feature is done without great documentation
Remove as much friction as possible: Have a development environment that Just Works™ and use the same workflows you're already using for reviewing code

Versioning and branching

It's important your team has an agreed upon strategy for versioning and branching documentation. We've written a whole article on versioning documentation, so we'll focus on branching strategies briefly in this section.

Choosing the right branching structure depends on your repository layout and team preferences. The goal is to ensure it's clear which documentation changes are associated with a specific product change.

As mentioned above, in the multi-repo case the docs changes may be in the same pull-request. In the multi-repo case, there may be branches in different repositories with matching names.

Having your team is aligned on your branching strategy makes releasing changes much more fluid and removes confusion.

Conclusions

Continuous documentation is not just a practice, but a mindset shift in how we approach documentation.

Here are the main takeaways:

Embrace small, iterative changes

Continuous documentation thrives on the principle of making small, manageable updates to documentation.

Foster a culture of documentation

By empowering all team members, from engineers to product managers, to contribute to documentation, we create a culture where documentation is everyone's responsibility.

Leverage automation and CI/CD integration

Integrating documentation processes into CI/CD pipelines streamlines updates, making documentation an integral part of the development workflow.

Generating an OpenAPI/Swagger spec from a Ruby on Rails API

Nik Begley — Tue, 13 Jun 2023 13:09:10 +0000

In this post we will go through how to generate an OpenAPI (previously Swagger) API reference from a Ruby on Rails application serving an JSON REST API.

OpenAPI has become an industry standard for describing APIs, and companies commonly publish OpenAPI specs for documentation and code generation purposes.

We will be creating a "Coffee Ordering API" using Ruby on Rails, and using a tool called rswag to create tests that verify the behaviour of our API and generate an OpenAPI reference.

Note: You can view the source code for this tutorial on GitHub

Creating the app

(We are going to assume for the purposes of this demo that you have both Ruby and Rails installed on your machine. We recommend the Rails Guides if you need help getting started.)

We are using Rails 7.0.2 and Ruby 3.1.2 for this example.

First, let's create a new app! We are going to skip some best practices here in order to get something we can play with quickly.

rails new coffee_shop --api
cd coffee_shop

We are passing the --api flag to skip some code generation, as we are not going to be serving any HTML from this app, only JSON.

Data model

Next, we will create our data model, the Order.

Create a migration for it:

./bin/rails g model Order kind price:integer customer

We can also update the migration to make sure our fields are required on the database level:

# db/migrate/<timestamp>_create_orders.rb
class CreateOrders < ActiveRecord::Migration[7.0]
  def change
    create_table :orders do |t|
      t.string :kind, null: false
      t.decimal :price, null: false
      t.string :customer, null: false

      t.timestamps
    end
  end
end

Remember to migrate your database!

./bin/rails db:migrate

Let's also add some validations into our model:

# app/models/order.rb
class Order < ApplicationRecord

  validates :kind, presence: true
  validates :price, presence: true, numericality: { greater_than: 0 }
  validates :customer, presence: true
end

Controller

Next, let's create a controller. We will put it under an Api namespace, since we want to prefix the API routes with /api.

./bin/rails g controller Api::Orders

Next, make sure we specify a route for this controller.

# config/routes.rb
Rails.application.routes.draw do

  namespace :api do
    # We will only care about a couple actions in this example
    resources :orders, :orders, only: [:index, :show, :create]
  end
end

On to the controller! We will define:

An index method for listing all orders
A show method for getting the details of a single order
A create method for creating a new order

class Api::OrdersController < ApplicationController
  def index
    @orders = Order.all

    render json: @orders, except: [:created_at, :updated_at]
  end

  def show
    @order = Order.find(params[:id])

    render json: @order, except: [:created_at, :updated_at]
  rescue ActiveRecord::RecordNotFound
    render json: { error: "Order not found" }, status: :not_found
  end

  def create
    @order = Order.new(order_params)

    if @order.save
      render json: @order, except: [:created_at, :updated_at]
    else
      render json: @order.errors
    end
  end

  private

  def order_params
    params.require(:order).permit(:kind, :price, :customer)
  end
end

Taking it for a spin

Great! We're ready to try out the API. Let's start the Rails local server:

./bin/rails s

We can now test our controller and see it in action:

curl
  -XPOST \
  -H 'Content-Type: application/json' \
  -d '{"order": {"price": "2.3", "customer": "Nik", "kind": "Espresso"}}' \
  localhost:3000/api/orders
#=> {"id":1,"kind":"Espresso","price":"2.3","customer":"Nik"}

It works! Lets list all the orders:

curl \
  -H 'Content-Type: application/json' \
  localhost:3000/api/orders
#=> [{"id":1,"kind":"Espresso","price":"2.3","customer":"Nik"}]

And what about fetching a single order?

curl \
  -H 'Content-Type: application/json' \
  localhost:3000/api/orders/1
#=> {"id":1,"kind":"Espresso","price":"2.3","customer":"Nik"}

Looking good. Let's move on to describing this API with OpenAPI.

Describing REST APIs with rswag

This is where rswag comes in. It is an extension to rspec-rails for "describing and testing API operations".

The workflow is as follows:

Create tests under spec/requests that describe your API
Add OpenAPI annotations to your tests
Run your tests to ensure the arguments and results conform to the expected shape
Generate an OpenAPI spec once tests pass

rswag also includes a bundled version of Swagger UI if you want to inspect your OpenAPI spec visually during testing.

Installing rswag

First, we install rswag. Let's add them to our Gemfile:

gem 'rswag-api'
gem 'rswag-ui'

group :development, :test do
  gem 'rspec-rails'   # Note that we also need rspec-rails
  gem 'rswag-specs'
end

Install your new dependencies:

./bin/bundle install

Next, run the installers for rswag and rspec-rails:

# rspec-rails
rails generate rspec:install

# rswag
./bin/rails g rswag:api:install && ./bin/rails g rswag:ui:install && RAILS_ENV=test ./bin/rails g rswag:specs:install

This will set up the boilerplate needed to execute our rswag tests.

Creating the spec

Next, let's create a spec to describe our API:

./bin/rails generate rspec:swagger Api::Orders

This will generate a spec file for you under spec/requests/api/orders_spec.rb. Open it up and inspect its contents. Let's take a look at the very first test, which describes the index method:

# spec/requests/api/orders_spec.rb
require 'swagger_helper'

RSpec.describe 'api/orders', type: :request do

  path '/api/orders' do

    get('list orders') do
      response(200, 'successful') do

        after do |example|
          example.metadata[:response][:content] = {
            'application/json' => {
              example: JSON.parse(response.body, symbolize_names: true)
            }
          }
        end
        run_test!
      end
    end

# ...

rswag's DSL tries to mirror OpenAPI's structure. We have here a path method, which takes a block for describing the operations under that path. In this case, we see the get HTTP method for this path, which is handled by the OrdersController's index method.

This spec says that we just expect it to return a 200 response, but does not say anything about what it should return. We will be changing this shortly.

Defining common objects

A common thing to do in OpenAPI is to create schema components that are reusable in your spec. This is commonly done for objects that show up in multiple places, or common errors.

In our case we are dealing with a single type of object: the Order model. Let's create a reusable component for it.

rswag has created a helper file for you under spec/swagger_helper.rb. It contains is the root of your OpenAPI specification into which the description from your specs will be injected. This is where we can describe out order model:

# spec/swagger_helper.rb
require 'rails_helper'

RSpec.configure do |config|
  config.swagger_root = Rails.root.join('swagger').to_s

  config.swagger_docs = {
    'v1/swagger.yaml' => {
      openapi: '3.0.1',
      info: {
        title: 'Coffee Shop API V1',
        version: 'v1'
      },
      paths: {},
      components: {
        schemas: {
          not_found: {
            type: 'object',
            properties: {
              message: { type: :string }
            }
          },
          order: {    # << This is where we describe our order
            type: 'object',
            required: [:kind, :price, :customer],
            properties: {
              kind: {
                type: :string,
                example: "Espresso"
              },
              price: {
                type: :string,
                pattern: "^\\d*\\.?\\d*$",
                example: "1.2",
                description: "Price, formatted as a string"
              },
              customer: {
                type: :string,
                example: "Alice"
              },
            }
          },
        },
      },
      servers: [
        {
          url: 'https://{defaultHost}',
          variables: {
            defaultHost: {
              default: 'www.example.com'
            }
          }
        }
      ]
    }
  }

  config.swagger_format = :yaml
end

See line 23 of the example - this is where we describe our reusable component. You can also set other things in this config file, such as your API version, your endpoint URL, and other metadata.

Describing operations

Let's take our index example and expand the spec that was autogenerated for us:

# spec/requests/api/orders_spec.rb
# ...
get('List orders') do
  tags 'Orders'
  consumes 'application/json'
  produces 'application/json'
  description "List all orders in the system"

  response(200, 'successful') do
    schema type: :array, items: { "$ref" => "#/components/schemas/order" }

    let!(:order1) { Order.create(kind: "Latte", price: 2.8, customer: "Bob") }
    let!(:order2) { Order.create(kind: "Espresso", price: 0.1, customer: "Eve") }

    after do |example|
      content = example.metadata[:response][:content] || {}
      example_spec = {
        "application/json"=>{
          examples: {
            test_example: {
              value: JSON.parse(response.body, symbolize_names: true)
            }
          }
        }
      }
      example.metadata[:response][:content] = content.deep_merge(example_spec)
    end

    run_test!
  end
end
# ...

Here we've done a number of things:

Added a tag to the operation. Tags are used to group common operations together, and tools that consume OpenAPI will use this information.
Set the Accepts and Content-Type header requirements
Set a description for the operation. Note that according to the OpenAPI spec you can use Markdown in any description field!
We refer to the order shared component with a $ref, telling OpenAPI this is the shape of the returned object for the operation.

(NOTE: rswag has a "bug" that causes response schemas to be empty in the final OpenAPI spec, unless the produces method is called specifying the return content type. Thank you to this person for pointing me in the right direction).

Finally, we've taken advantage of a really cool rswag feature: automatic example generation.

When the test is run, we can take the output the operation returned and use it in our OpenAPI spec examples. In this example, we create 2 orders, which will be returned by the list operation, and serialised into our OpenAPI example.

We'll do the same for the other two operations:

# spec/requests/api/orders_spec.rb
# continued from above...

    post('create order') do
      tags 'Orders'
      consumes 'application/json'
      produces 'application/json'
      description "Create a new order. **NOTE**: Price is set by customer! Do not go to production."

      parameter name: :order, in: :body, schema: { "$ref" => "#/components/schemas/order" }

      response(200, 'successful') do
        schema "$ref" => "#/components/schemas/order"

        let!(:order) {
          {
            kind: "Espresso",
            price: 0.2,
            customer: "Eve"
          }
        }

        after do |example|
          content = example.metadata[:response][:content] || {}
          example_spec = {
            "application/json"=>{
              examples: {
                test_example: {
                  value: JSON.parse(response.body, symbolize_names: true)
                }
              }
            }
          }
          example.metadata[:response][:content] = content.deep_merge(example_spec)
        end

        run_test!
      end
    end
  end

  path '/api/orders/{id}' do
    parameter name: 'id', in: :path, type: :integer, description: 'The ID for the order'

    get('show order') do
      description "Get the details for a particular order"

      produces 'application/json'

      response(200, 'successful') do
        schema "$ref" => "#/components/schemas/order"

        let(:order) { Order.create(kind: "Latte", price: 0.8, customer: "Bob") }
        let(:id) { order.id }

        after do |example|
          content = example.metadata[:response][:content] || {}
          example_spec = {
            "application/json"=>{
              examples: {
                test_example: {
                  value: JSON.parse(response.body, symbolize_names: true)
                }
              }
            }
          }
          example.metadata[:response][:content] = content.deep_merge(example_spec)
        end

        run_test!
      end

      response(404, 'not found') do
        schema "$ref" => "#/components/schemas/not_found"

        let(:id) { 999999999 }

        after do |example|
          content = example.metadata[:response][:content] || {}
          example_spec = {
            "application/json"=>{
              examples: {
                test_example: {
                  value: JSON.parse(response.body, symbolize_names: true)
                }
              }
            }
          }
          example.metadata[:response][:content] = content.deep_merge(example_spec)
        end

        run_test!
      end
    end
  end
end

Note that for the show action we supply two response examples: a 200 and 404 response. We could do the same for the errors that could be returned from the create action, but we'll leave that as an exercise for the reader.

Running the tests

Let's run the tests! If we did everything correctly, we should see all green.

bundle exec rspec ./spec/requests/api/orders_spec.rb
# ...
# 
# Finished in 0.03847 seconds (files took 0.51792 seconds to load)
# 3 examples, 0 failures

Success!

Let's try changing something in our spec, and see if the test catches it. We will make a change to the shared order model under spec/swagger_helper.rb so that the customer should be an integer instead of a string and run the tests again.

bundle exec rspec ./spec/requests/api/orders_spec.rb

#   ...a gigantic stacktrace...
# 
#   2) api/orders /api/orders post successful returns a 200 response
#      Failure/Error:
#        raise UnexpectedResponse,
#              "Expected response body to match schema: #{errors.join("\n")}\n" \
#              "Response body: #{JSON.pretty_generate(JSON.parse(body))}"
# 
#      Rswag::Specs::UnexpectedResponse:
#        Expected response body to match schema: The property '#/customer' of type string did not match the following type: integer in schema ba752ce3-171a-5719-945f-62b5f5cd1cf5#
#        Response body: {
#          "id": 1,
#          "kind": "Espresso",
#          "price": "0.2",
#          "customer": "Eve"
#        }
# 
#   ...
# 
# Finished in 0.03698 seconds (files took 0.49892 seconds to load)
# 3 examples, 2 failures
# 
# Failed examples:
# 
# rspec ./spec/requests/api/orders_spec.rb:12 # api/orders /api/orders get successful returns a 200 response
# rspec ./spec/requests/api/orders_spec.rb:43 # api/orders /api/orders post successful returns a 200 response

I've shortened the output of rspec significantly to focus on the important parts. Rswag correctly realised that we returned a string for our customer field instead of an integer, like the OpenAPI spec described.

This means we can verify that our OpenAPI spec matches the actual implementation of our server automatically. If we run these checks in CI/CD, our spec should never be out of date.

Generating the OpenAPI spec

As a final step, let's actually generate the final OpenAPI spec for this API:

SWAGGER_DRY_RUN=0 RAILS_ENV=test ./bin/rails rswag

# Generating Swagger docs ...
# Swagger doc generated at ./coffee_shop/swagger/v1/swagger.yaml
# 
# Finished in 0.06065 seconds (files took 0.504 seconds to load)
# 3 examples, 0 failures

rswag just generated our OpenAPI file under swagger/v1/swagger.yml. Let's take
a look:

---
openapi: 3.0.1
info:
  title: Coffee Shop API V1
  version: v1
paths:
  "/api/orders":
    get:
      summary: List orders
      tags:
      - Orders
      description: List all orders in the system
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                test_example:
                  value:
                  - id: 1
                    kind: Latte
                    price: '2.8'
                    customer: Bob
                  - id: 2
                    kind: Espresso
                    price: '0.1'
                    customer: Eve
    post:
      summary: create order
      tags:
      - Orders
      description: 'Create a new order. **NOTE**: Price is set by customer! Do not
        go to production.'
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                test_example:
                  value:
                    id: 1
                    kind: Espresso
                    price: '0.2'
                    customer: Eve
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/order"
  "/api/orders/{id}":
    parameters:
    - name: id
      in: path
      description: The ID for the order
      required: true
      schema:
        type: integer
    get:
      summary: show order
      description: Get the details for a particular order
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                test_example:
                  value:
                    id: 1
                    kind: Latte
                    price: '0.8'
                    customer: Bob
        '404':
          description: not found
          content:
            application/json:
              examples:
                test_example:
                  value:
                    error: Order not found
components:
  schemas:
    not_found:
      type: object
      properties:
        error:
          type: string
    order:
      type: object
      required:
      - kind
      - price
      - customer
      properties:
        kind:
          type: string
          example: Espresso
        price:
          type: string
          pattern: "^\\d*\\.?\\d*$"
          example: '1.2'
          description: Price, formatted as a string
        customer:
          type: string
          example: Alice
servers:
- url: https://{defaultHost}
  variables:
    defaultHost:
      default: www.example.com

There we have it! An OpenAPI spec, generated automatically from our code, verified by tests to match our actual implementation. This spec can now be used to generate client SDKs or API reference documentation.

Recap

So, we now have:

A JSON API with 3 actions
Tests that verify the implementation
Automatically generated OpenAPI specifications

If you are using Ruby on Rails, this can be a very effective way to produce accurate OpenAPI specifications.

That being said, there is no free lunch. Especially when producing API documentation from OpenAPI, you have to put effort into adding helpful descriptions and lots of examples for your operations. Users won't find a bare bones OpenAPI reference useful. But a well maintained and annotated one can make an API shine.

But with a setup like this, you are well on your way to using OpenAPI effectively!

Export an OpenAPI specification from your FastAPI app

Nik Begley — Fri, 19 May 2023 08:14:50 +0000

FastAPI is a modern Python web framework for building APIs. FastAPI is a great choice for building simple APIs, and it comes with built-in support for generating OpenAPI documentation.

In this post we will look at how to generate and extract the OpenAPI specification from a FastAPI project.

A simple single-file FastAPI example taken from the official docs will suffice as our testbed. The same workflow will also work for larger projects with routers.

Step 1: Add Tags and Metadata

Chances are that you'll use the OpenAPI spec to generate documentation or code. It is important to add metadata to your FastAPI app so that the generated OpenAPI spec is complete.

Firstly, you should tag our endpoints with tags to make sure they are grouped in logical operations. This example does not use routers, but if you do, you need to tag the router instead of the endpoint.

Tags are used by documentation and code generators to group endpoints together. Tags may include spaces and special characters, but we recommend to keep the tags simple. It is common to use either lowercase or Capital Case for tags, like Items in our example.

In addition to tags, we'll add a description and version metadata to our FastAPI app instance. The description and version will be used in the generated OpenAPI docs on the overview page. You can find the full list of metadata parameters in the FastAPI docs if you need to include additional details in your specification.

The full example main.py now looks like this:

# main.py
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(description="Example app", version="0.1.0")


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []


@app.post("/items/", tags=["Items"])
async def create_item(item: Item) -> Item:
    return item


@app.get("/items/", tags=["Items"])
async def read_items() -> list[Item]:
    return [
        Item(name="Portal Gun", price=42.0),
        Item(name="Plumbus", price=32.0),
    ]

This example requires pip install fastapi[all] and pip install pydantic to run.

Step 2: Create the Export Script

By default FastAPI will generate OpenAPI docs under /docs. You can try this out by running the app and navigating to http://localhost:8000/docs.

It is possible to get the OpenAPI JSON directly by navigating to /openapi.json, but we'll want to extract the document programmatically in order to be able to automate the process. FastAPI does not support exporting the OpenAPI specification directly, but we'll use a small script to extract it.

Create a file extract-openapi.py with the following contents:

# extract-openapi.py
import argparse
import json
import sys
import yaml
from uvicorn.importer import import_from_string

parser = argparse.ArgumentParser(prog="extract-openapi.py")
parser.add_argument("app",       help='App import string. Eg. "main:app"', default="main:app")
parser.add_argument("--app-dir", help="Directory containing the app", default=None)
parser.add_argument("--out",     help="Output file ending in .json or .yaml", default="openapi.yaml")

if __name__ == "__main__":
    args = parser.parse_args()

    if args.app_dir is not None:
        print(f"adding {args.app_dir} to sys.path")
        sys.path.insert(0, args.app_dir)

    print(f"importing app from {args.app}")
    app = import_from_string(args.app)
    openapi = app.openapi()
    version = openapi.get("openapi", "unknown version")

    print(f"writing openapi spec v{version}")
    with open(args.out, "w") as f:
        if args.out.endswith(".json"):
            json.dump(openapi, f, indent=2)
        else:
            yaml.dump(openapi, f, sort_keys=False)

    print(f"spec written to {args.out}")

What this script does is import the app from the given import string, and then call app.openapi() to get the OpenAPI spec. The spec is then written to the given output file.

You can invoke help to see the available options:

$ python3 export-openapi.py --help
usage: extract-openapi.py [-h] [--app-dir APP_DIR] [--out OUT] app

positional arguments:
app App import string. Eg. "main:app"

options:
-h, --help show this help message and exit
--app-dir APP_DIR Directory containing the app
--out OUT Output file ending in .json or .yaml

If you have trouble with the uvicorn import, make sure you have installed the fastapi[all] package, which includes uvicorn, or that you have uvicorn installed.

Step 3: Export OpenAPI spec from FastAPI

Running the script

To run the export script, you need to know the import string of your FastAPI app. The import string is is what you pass to uvicorn when running your app, like uvicorn main:app.

This depends on where your code is located, and what the FastAPI instance is called. See below for tips on how to determine the import string.

# Run the script by passing the import string of your FastAPI app
# If you don't know the import string, see below for examples
$ python extract-openapi.py main:app

This should create an openapi.json or openapi.yaml file in your current directory.

Example case: simple project structure

In our example, we have a project structure like this:

/my_project
├── extract-openapi.py
└── main.py

Our FastAPI instance is app since we wrote app = FastAPI() in main.py. We also have a single file main.py in the current directory, so the import string is main:app.

To extract the OpenAPI spec we do

$ python extract-openapi.py main:app

Example case: nested project structure

For larger applications, the project structure is often more nested, like this:

/my_project
├── extract-openapi.py
└── myapp
    └── main.py

In this case we'll have to add the module name, myapp, to the import string. The import string is now myapp.main:app. Alternatively, if you are having trouble with this, you can use the --app-dir argument to specify the directory containing the entrypoint of your application.

In this case, to extract the OpenAPI spec we do

$ python extract-openapi.py myapp.main:app

# or alternatively

$ python extract-openapi.py --app-dir myapp main:app

You should now have the openapi.json or openapi.yaml file in your current directory.

Step 4: Automate in your CI/CD pipeline (optional)

How you'll integrate the extraction to your CI/CD depends on what you are trying to accomplish. The three most common ways to approach this are:

Extract the spec locally and commit it to your repository. Let CI/CD verify the committed spec is up-to-date.
Extract the spec as part of your CI/CD pipeline, and use the spec as a temporary file to accomplish something (eg. generate a client).
Extract the spec as part of your CI/CD pipeline, and commit the generated spec to your repository, when merging to main.

The benefit with using a script is that it can also be run locally. Locally committing is often a safe and straight-forward approach, but may occasionally make merging more difficult. If, however, you only need to generate the OpenAPI spec as part of your CI/CD pipeline, you should also consider dedicated GitHub Actions.

As an example, we'll demonstrate a GitHub Actions job, which verifies that the committed spec matches a generated one:

# .github/workflows/main.yml
name: CI

on: [push]

jobs:
   extract-openapi:
      runs-on: ubuntu-latest
      steps:
         - uses: actions/checkout@v2

         - name: Setup Python
         uses: actions/setup-python@v2
         with:
            python-version: 3.11

         - name: Install dependencies
         run: |
            python -m pip install --upgrade pip
            pip install -r requirements.txt

         - name: Extract OpenAPI spec
         run: python extract-openapi.py main:app --out openapi_generated.yaml

         # Do something with the generated spec here.
         # For example, validate that the committed spec matches the generated one.
         - name: Verify OpenAPI spec has been updated
         run: git diff --exit-code openapi.yaml openapi_generated.yaml

Summary

In summary, we have

Added tags to each endpoint or router
Added description, version and other metadata to our FastAPI app instance
Created a script extract-openapi.py to extract the OpenAPI spec from FastAPI
Automated the extraction in CI/CD pipeline

How AI is changing documentation

Nik Begley — Wed, 17 May 2023 13:25:18 +0000

Documentation has been one of the earliest fields to see large changes due to ChatGPT, and more recently GPT-4. Especially technical documentation, being in the intersection of AI-tinkerers (programmers) and written content, has seen a lot of movement. We've seen experiments in generating documentation, new ways of interacting with documentation, and lots of people wondering what the future will look like.

We at Doctave are, for obvious reasons, looking at this space carefully. In this post will take a look at the AI-powered documentation landscape: what we have seen work and not work so far. And finally, we will make some guesses about what the future holds.

Disclaimer: Things are moving fast

I am writing this in mid-May of 2023. The pace of change in AI means that the opinions and statements of fact in this piece may be out of date very quickly.

As an example, less than a week ago, as of time of writing, Anthropic announced 100K context windows for their Claude model: equivalent to around 75,000 words. This may already change the dynamics discussed in this post when released to the public.

This post will also only focus on AI in the context of (technical) documentation, instead of AI capabilities broadly, which should not be underestimated.

It's important to stay humble when things are moving this fast.

What we've seen so far

AI applied to documentation has touched how we both read and write documentation.

On the writing side, OpenAI's Codex model, powering GitHub Copilot, has turned out to be great at understanding what a piece of source code is doing and producing documentation at least at the function level. ChatGPT has also proved to be a valuable tool for expanding, rewording, or editing any type of prose: including documentation.

On the reading side, companies have started adding AI-powered chat interfaces to their docs. And for popular tools you can even get ChatGPT to tell you the incantation you need without having to even look at the docs.

These are just the earliest experiments, but let's dive into them a bit.

AI-powered documentation chat

Chat interfaces powered by OpenAI's API was one of the first things people started playing with. It was an obvious leap from the ChatGPT interface: what if you could have a discussion with an AI that knows everything about your documentation?

As far as I can tell, Supabase was the first large company to add such an interface (aptly named "Clippy") to their developer documentation:

Since then, a long list of companies have built such interfaces for their documentation. Similarly, companies providing documentation platforms have added such features to their offering. Not only that, there are companies whose whole business is building chat interfaces over whatever content you can throw at them: be it technical documentation, CRM content, or sales meeting transcripts.

How do they work?

These chat interfaces are quite straightforward to build these days. In fact, OpenAI has a guide on how to build them in their documentation.

Split your content into topical sections
Create embeddings with OpenAI for your sections
Index your embeddings in a database (Postgres works great, but this use case among others has caused an explosion in vector database startups).
Create an embedding for your user's question through OpenAI
Run a query against your embeddings to find the ones that are the closest matches with the question's embedding. (Embeddings are arrays of numbers, so it is possible to compute a "distance" between different embeddings).
Include the closest matches as "context" for your final OpenAI completion call, followed by your user's query

What is the experience like?

Having tried out a number of the customised documentation chat interfaces so far, the experience has been slightly underwhelming. Especially considering the incredible success of ChatGPT, it was surprising to find that these chat interfaces for documentation seemed to be less helpful than traditional search.

We think there are two main issues with these documentation chat interfaces:

Speed of answering
Accuracy and helpfulness

Both of these issues seem to be preventing chat interfaces from being the 10x improvement we can imagine them being at the moment.

Call me when you're done

If you have not done so yet, I encourage you to try using a chat interface for a documentation site. What you will find is that it is painfully slow.

While the GPT-3.5 model can be incredibly fast today, for documentation you likely want to use the most powerful GPT-4 based model, which is just plain slow. You can end up waiting for even up to a minute for the AI to complete its response.

We have decades of experience building search engines that understand spelling mistakes, synonyms, and work in milliseconds. Going to a system that takes 10s of seconds to surface more or less the same information seems like a step backwards.

But, this is absolutely a short-term problem.

We have no doubt that OpenAI (and competitors?) will improve their algorithms, computational power will increase, and these models will become faster over time. But for now, we only have painfully slow assistants that make you think "forget it, I'll do it myself".

Trust issues

Speed would not be a problem if the answers these systems produced were stellar. But the responses have not reached the helpfulness expected of ChatGPT.

At the heart of this, we believe, are hallucinations. Hallucinations have been a well-known problem from the day ChatGPT was launched. In short: AIs will make things up.

Luckily, hallucinations have not been a huge issue with documentation chat AIs. Likely because they tend to set their temperature to, or close to 0. Temperature, in OpenAI's terminology, means how "random" the answer will be. From their documentation:

Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

With a low temperature the answers seem to stick to the truth and be quick to say "I don't know" if it cannot find an answer in its provided context. Documentation is an area where incorrect answers can cause a lot of frustration. Since there isn't a human in the loop verifying the answers of these chat interfaces, companies tend to be conservative in the responses they want their AI to give.

Still, in our testing we have seen documentation AIs produce bogus information. Supabase for this reason has the following disclaimer:

The unfortunate net effect is that the answers are...bland. Low temperatures mean the model is unable to fill gaps in your documentation and reason about how your product works.

To give an example, asking one of these documentation assistants if the tool they describe has a Ruby client, when it doesn't, will most of the time cause it to respond with "I don't know", instead of the more helpful "We don't have a Ruby client, but we do have official API wrappers in X, Y and Z languages".

If the context the AI is provided does not verbatim have the information it needs to respond, it will not be able to give an answer. At which point, is this really better than search yet?

Unlike with the speed issue, hallucinations and accuracy are problems that we have zero solutions for. We have no idea how to stop Large Language Models (LLMs) from lying, which does not bode well for AI alignment overall. It remains to be seen if we can thread the line between a system that can only repeat almost verbatim what is found in your content, and a more helpful assistant that is able to correctly infer more information from your documentation.

Obvious potential

It is easy to imagine how having a GPT-4 level chat assistant trained on your documentation could be incredibly useful. It could personalise examples on demand, write customised tutorials, and infer how to use your product from e.g. your OpenAPI specifications and documentation.

Imagine being new to a library or product, telling an LLM you are familiar with XYZ technologies, and creating a customised learning path for you to get started based on techniques and technologies you already understand.

Currently we have not seen this become a reality.

In our experience, it is faster and more convenient to use traditional search and skim through documentation yourself to find the answers you are looking for.

Interestingly, it is not possible for anyone but OpenAI (or its competitors) to fix these issues. All those startups built around making chat interfaces for your content will have to wait until the state of the art moves forward.

That being said, we look forward to revisiting this opinion in 3 ~~days~~ months!

Generating documentation

Ok, we started with the reading part. What about writing documentation? Here we see AI being much more helpful today and already making the lives of developers and technical writers easier.

(We will focus mostly on long-form technical writing here, instead of e.g. generating docstrings for your functions, which also works great.)

We have seen companies like Jasper pop up to help with AI-powered content generation (built on OpenAI, naturally), but Notion was one of the first companies to integrate OpenAI's models into their own product. In Notion, the AI is an assistant: summarising, rewording, and improving your content on demand.

AI-assisted technical writing

All writing jobs were changed the moment ChatGPT was released. Documentation is no different. Assuming AI models don't take over technical writing completely (we'd likely have bigger disruptions at that point), how can we use AIs effectively in technical writing?

There are some obvious cases that you can achieve even with just using the Chat GPT interface today:

Summarising or expanding text
Simplify or clarify your writing
Maintaining a consistent tone of voice
Generating guides from API references
Format Markdown tables for us...

But can we do better? What could the future have in store?

Customised learning paths

We often come back to this diagram (source) when thinking about structuring documentation:

The idea is that your documentation should try to cover all 4 aspects:

Tutorials: for new users to learn the basics of your product
How-to guides: for users trying to solve specific problems
Explanations: to help users better understand the concepts behind your product
References: for describing low level details of the system

Where we see a lot of opportunities for LLMs to help are with the first 3 sections.

LLMs could help produce more specialised how-to guides and tutorials than human writers can. Not only that, you could create multiple versions of the same guide that match the background of the reader.

You have a Ruby background? Here is a Rust tutorial tailored for a Ruby programmer. Familiar with MySQL? Here is a MongoDB tutorial that explains its usage in terms you already understand.

The reference is also an interesting case. You may have OpenAPI specifications or type signatures that describe the low level workings of your system. Well annotated references can be a great starting point for an LLM to start understanding how your product works in order for it to produce accurate and helpful content.

How does the AI know?

All of the above implies that the LLM understands how your product/tool/library works. How does it gain that knowledge?

Currently, the only way is through, wait for it... documentation!

Ironically, it is the quality of your documentation that will determine if an LLM can be a useful assistant for your product or not. Current techniques, as described above, require you to ship your documentation to the LLM in order for it to generate its response. If your prompt is poor quality, the LLM is going to do a poor job.

This feels like a chicken-or-egg problem, but ultimately means that you cannot escape writing documentation. What is more likely is writers providing LLMs the context they need to assist in the generation of documentation: through annotated API specifications like OpenAPI or GraphQL, or longer written guides.

This is of course another area of great uncertainty. Perhaps someone will create a system that lets LLMs interact with your tool to learn how it works? Or, could the model eventually understand your product by simply reading its source code? There are movements in both these directions, but it is too early to say if these experiments pan out.

Making your documentation "AI Ready"

Anyone who claims they can see how the world will pan out is likely incredibly naive. But that never stopped anyone from speculating!

It remains to be seen if chat interfaces will be useful, or simply a fad in the beginning of the AI revolution. Or if they do remain, where will the chatting happen?

OpenAI announced ChatGPT Plugins in March 2023, which let ChatGPT fetch information from external live data sources. Now you have one powerful LLM that is able to integrate with other tools and services.

Will people be using multiple AI chat assistants, e.g. one per service, or just a single main assistant that knows how to talk to various data sources?

Perhaps it will make more sense for your documentation to be "AI-ready", instead of you building your own chat interface. The task of the technical writer would be to ensure both humans and AIs are able to interact with the documentation in an effective way.

Regardless, what is quite probable is best practices emerging around how to make your documentation easily digestible by LLMs.

What to look out for in the future

This is all incredibly speculative, and we live in a strange time. Depending on who you ask, we should be worried, or incredibly excited for a beautiful future where AIs make our world a better place. Documentation is a tiny part of this broader discussion, but it is interesting because it sits in the nexus of people playing with AI and written content. Things are moving fast.

There are a few things to keep an eye on going forward:

When will GPT-4 or equivalent models become significantly faster?
Will we get better at limiting hallucinations allowing for more creative but accurate AI assistants?
Will we end up using one or more AI assistants?

One thing seems clear for now: you still need to write the docs.

Should You Use Docs-as-Code?

Anton Rautio — Thu, 11 May 2023 08:27:13 +0000

So you've heard about docs-as-code and are wondering if it's right for your project. When deciding whether to implement docs-as-code for your documentation projects, it's essential to weigh the unique aspects of your project, such as quality standards, project requirements, and the nature of contributions. Understanding the benefits and requirements of docs-as-code will help you make an informed decision on whether it's the right approach for your specific needs. In this article we'll discuss some of the key considerations when deciding whether to use docs-as-code.

Balancing Quality Standards and Project Requirements

Every documentation project has unique quality standards and expectations. For internal documentation, the focus is often on accessibility and ease of use for company employees, making minor imperfections more acceptable.

On the other hand, external documentation demands a higher level of precision, especially for technical software products like APIs that other developers rely on. In these cases, the documentation directly reflects the quality of the product itself, as there may be no other user interface. For Software-as-a-Service products, while documentation quality remains important, surgical precision and constant updates may not be as critical.

Docs-as-code facilitates the creation of clear, accurate, and high-quality documentation by integrating objective quality standards and the review process.

Implement automated tests and validation tools to identify issues such as broken links, formatting inconsistencies, and content errors during the review process.
Enhance the review and feedback process with version control and change tracking systems, similar to code repositories.
Foster collaboration among developers, technical writers, and other stakeholders to ensure documentation accurately captures the product's features and functionality.
Pair documentation with code changes, ensuring that documentation is updated as the code changes and their history is linked.

Projects with any type of quality standards can benefit from docs-as-code as it's up to the project team to determine the level of quality they want to maintain, whether it's strict or a bit more relaxed.

Contribution Dynamics

The advantages of docs-as-code become more apparent based on how people contribute to your project. Adopting docs-as-code is particularly beneficial when:

You have an extensive team of developers, technical writers, and other stakeholders contributing to the documentation.
or, your project is open source, welcoming external contributions.

The degree of docs-as-code implementation one should aim for depends on the contributors' profiles. When developers and other stakeholders without professional writing experience contribute to the project, it's crucial to employ automated quality checks and other safeguards to uphold documentation standards. When doing so, it is equally important that the rationale behind such checks is communicated clearly to avoid confusion.

However, if your team consists of a smaller group of professional writers, these measures may be less of a priority.

Evaluating Automation Potential

Assessing the potential to automate aspects of your documentation process plays a crucial role in deciding whether to embrace docs-as-code.

If your product incorporates OpenAPI specifications, code comments, code examples, or other design artifacts, docs-as-code can save you time and minimize manual effort.

Integrating the documentation process into your development workflow enables you to:

Generate API documentation automatically from OpenAPI specifications, guaranteeing accuracy and consistency throughout your documentation.
Extract documentation from code comments or annotations, decreasing duplication and keeping the documentation current as the code changes.
Derive code examples directly from your source code, offering users precise and relevant examples that mirror your product's current state.
Automatically track documentation tasks in version-control linked trackers such as Linear so that they can be handled in a way similar to other product-related tasks.

By evaluating the automation potential in your documentation project, you can better determine if docs-as-code is the right approach for you.

Conclusion: Is Docs-as-Code Right for Your Project?

Docs-as-code offers a powerful solution for maintaining and enhancing your documentation quality. To determine if it's the right fit, consider your project's unique requirements, contribution dynamics, and automation potential. While not an exhaustive list, the following scenarios can help guide your decision:

Your project depends on design artifacts like OpenAPI specifications, code comments, or code examples, and automation could significantly reduce manual effort when keeping your docs up to date.
You're working on a project with specific quality standards and a diverse team of contributors. Automated quality checks, validation tools, and a robust review process are essential for preserving documentation quality.
You have a sizable engineering team that requires accurate internal documentation for various interfaces. Developers are the primary contributors.
You're managing an open-source project with a diverse range of contributors, where efficient collaboration, version control, and review processes are crucial.
Your project includes maintaining and updating documentation for multiple versions of a product separately.

Consider adopting docs-as-code if any of these scenarios apply to your project. If multiple points resonate, you should definitely implement docs-as-code.

Documenting REST APIs with OpenAPI

Nik Begley — Tue, 09 May 2023 13:13:55 +0000

Most APIs today are designed as RESTful APIs. REST (Representational State Transfer) is an architectural style for designing networked applications. RESTful APIs use HTTP to expose resources and perform operations on them using standard HTTP verbs, such as POST, GET, and DELETE.

In this post, we'll explore how to document RESTful APIs using OpenAPI, an industry-standard specification for describing, producing, consuming, and visualizing RESTful web services. We'll focus on documenting a single operation, its components, and the tools OpenAPI provides to create comprehensive documentation.

In this post we'll expect that you have a tool that is able to produce a documentation site for you given an OpenAPI spec. Doctave supports OpenAPI but these concepts are transferable to any tool.

What is in an operation?

In the context of a RESTful API, an operation refers to a single action you can perform. Each operation consists of the following components:

HTTP Verb (such as POST, GET, PUT, UPDATE, DELETE)
A URI path (such as /users)
Parameters
A request body

With these components, you can invoke the operation and receive a response. The response itself contains:

A response body
A status code
A content type

OpenAPI operation model

OpenAPI provides a standardized model for defining operations in RESTful APIs. In an OpenAPI document, operations are organized under the paths field. The paths field defines all possible URI paths for the API, and each path can have operations associated with different HTTP verbs:

paths: # <- Top level `paths` field
  /pets: # <- The URI path for the operation
    get: # <- The HTTP verb
      description: Returns all pets from the system
      responses:
        "200": # <- The response for a 200 OK status
          description: A list of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Pet"

(You can find all the examples used here in the official OpenAPI GitHub Repo)

Building on the this example, the /pets path is defined to handle a GET request. When a GET request is issued, it returns a list of objects describing the available pets. We can see here the main components of an operation: the URI path, the HTTP verb, and the response. Notice that in this case, the operation does not require any parameters or a request body.

For a more in-depth understanding of the different parts of OpenAPI, you can refer to the official OpenAPI specification. While it may be verbose, it serves as a valuable reference for comprehending how OpenAPI components work together.

Where does the documentation go?

OpenAPI was luckily built with documentation in mind. After all, it's designed to be used for generating human readable documentation, among other use cases. Most OpenAPI objects include a description field. You can see some in the example above! This field is your friend and a valuable tool for writing detailed explanations of the corresponding object

Additionally, you can use Markdown! The OpenAPI spec specifically states that description should support the CommonMark Markdown flavor. This means you can include clickable links, lists, and anything else you can describe in Markdown.

Some objects also feature a summary field, intended for concise descriptions of the operation's purpose.

Beyond these fields, it's important to consider clear and consistent naming for the objects and operations themselves in your API. It will help readers search and skim your docs quickly to find the sections they are looking for.

Parameters

If an operation is like a function in a programming language, parameters are like function arguments.

There are four of ways to pass parameters in an operation:

Query parameters
Path parameters
Headers
Cookies

Parameters are defined in the operation's parameters field:

/pets/{petId}:            # <- Note the URI path with a placeholder
  get:
    summary: Info for a specific pet
    operationId: showPetById
    tags:
      - pets
    parameters:            # <- List of parameters for this operation
      - name: petId
        in: path
        required: true
        description: The id of the pet to retrieve
        ...

The above operation says you can request details of a specific pet by specifying the pet ID as a path parameter. The in field for the parameter defines how to pass the parameter to the operation. It can be one of query, path, header, or cookie.

Additionally, each parameter can have an associated schema. Generally, these schemas are simple, as parameters are often IDs or short strings. More on these shortly!

Query and Path Parameters

Let's look at query and path parameters together. Since they are very similar.

Query parameters
- parameters at the end of the URI, after a ? as a series of key value pairs
Path parameters
- parameters in the path section of the URI

Here's a (slighty contrived) example operation for querying the history of a pet:

/pets/{petId}/history?page=2
      ───┬───         ───┬──
  path ──┘               │
 query ──────────────────┘

The petId path parameter is part of the URI path. Commonly these parameters are used when referencing a specific resource such as a user. Usually the parameter is in the form of a unique ID, such as an integer, or a unique username.

The query parameter in this case is the page=2 section. Query parameters are often used for pagination and filtering results. Although query parameters can be used to identify resources, it's not a common practice.

Headers

Headers can be thought of as metadata about the request. They are additional information sent along with the request, such as the User Agent, which determines what kind of client is making the request.

You will most likely encounter headers in reference to API authentication (see below), but there are other uses as well, such as specifying in what format the payload you are sending is, or what format you would like to receive.

Cookies

Cookies are less commonly used in HTTP APIs, but they may still appear in some cases. Similar to headers, cookies are often used by browsers for tasks like user authentication. However, in the context of APIs, their usage is relatively rare, as they go against the RESTful principle of statelessness.

OpenAPI schemas

Before moving on, let's address a key question:

How do you actually describe what the values of these various parameters should be? Can we specify that the page query parameter has to be an integer greater than zero? This is where OpenAPI schemas come in.

If we look at one of the previous examples:

paths:
  /pets:
    get:
      description: Returns all pets from the system
      responses:
        "200":
          description: A list of pets.
          content:
            application/json:
              schema: # <- NOTE the schema here
                type: array
                items:
                  $ref: "#/components/schemas/Pet"

On line 10, we state that the response should have a particular schema‚Äîan array of pets. The schema's item points to another part of the spec to a shared pet schema component. Let's see what that looks like:

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
          description: The name of the pet
        tag:
          type: string

Now we're talking! This is what a pet looks like.

The pet has a type of object. This means it has a number of properties, or fields. In this case we have id, name, and tag properties for this pet object.

This is where OpenAPI schemas gets really cool: they can be nested. Pet is a schema defining an object, and the properties each define child schemas. The id property is a schema with a type of integer.

This allows for the definition of complex, deeply nested objects.

Also, each schema can include the previously described description field. Which means you can document every property as required.

You can also specify all kinds of other requirements and constraints in schemas. A non-exhaustive list includes:

Maximum and minimum values (for numeric types)
Maximum and minimum length (for string types)
A list of possible values (enums)
A regular expression pattern

I highly recommend reading the official OpenAPI guides on schemas for more examples.

Request Body

Ok, with the schema detour out of the way, lets move onto request bodies, where schemas play a big part!

POST, PUT, and UPDATE HTTP requests usually contain a request body. This is the payload you want to send to the server along with the request. It will most likely be JSON encoded string, though other formats are possible.

As with parameters, the request body is in fact one large schema definition:

/pets:
  post:
    description: Creates a new pet in the store. Duplicates are allowed
    requestBody:
      description: Pet to add to the store
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/NewPet"

Here we again refer to a shared component schema to define the shape of the request body, this time called NewPet:

components:
  schemas:
    NewPet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        tag:
          type: string

This looks very similar to the parameter examples. Turns out OpenAPI is just schemas all the way down.

One thing to note about request bodies is that they are placed under a content type. In this case, it's application/json, meaning that the request body should be encoded as JSON.

Responses

Responses are what the operation returns to you under various conditions. Just like the request body, the response shape is defined using schemas.

Since the server can return multiple different statuses, you can define schemas for each of the HTTP status codes. For example, if you are creating a resource by calling the operation, you should return a 201 status. This in itself documents that something was created.

/pets:
  post:
    description: Creates a new pet in the store. Duplicates are allowed
    operationId: addPet
    requestBody:
      description: Pet to add to the store
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/NewPet"
    responses: # <- NOTE responses here
      "201":
        description: pet response
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      default:
        description: unexpected error
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Error"

In this example, we see that creating a pet has two possible responses: a pet, or an error. A 201 status will return the pet, but any other status code (using the default catch-all) will return the error.

Again, just as with request bodies, the schemas are located under the content type of the response.

Errors

It's worth talking for a moment about errors in general.

Proper error handling is important in order to have a developer-friendly API. If your API spews out a generic an error occurred, try again message when the inputs are not just right, you will have a lot of frustrated users.

OpenAPI allows you to document error responses alongside your successful responses too. Errors work just like regular responses. Consider thinking carefully what your various 4xx status responses return, and documenting them along with your happy paths.

It's also important to use proper status codes for the type of error you are returning. For example:

403 when accessing a resource the user is not authorized for
404 when the resource does not exist
418 when the server is a teapot

Consider also returning a human-readable description of the error in the body of the error response. It can actually limit your support load and let people debug their issues themselves.

Examples

Something we have not yet mentioned about request bodies and responses are examples. You can give concrete examples of what the body of a request should look like for each case.

Here's a (verbose) example (pun intended):

/:
  get:
    operationId: listVersionsv2
    summary: List API versions
    responses:
      "200":
        description: |-
          200 response
        content:
          application/json:
            examples: # <- Example responses for this status
              foo:
                value:
                  {
                    "versions":
                      [
                        {
                          "status": "CURRENT",
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links":
                            [
                              {
                                "href": "http://127.0.0.1:8774/v2/",
                                "rel": "self",
                              },
                            ],
                        },
                        {
                          "status": "EXPERIMENTAL",
                          "updated": "2013-07-23T11:33:21Z",
                          "id": "v3.0",
                          "links":
                            [
                              {
                                "href": "http://127.0.0.1:8774/v3/",
                                "rel": "self",
                              },
                            ],
                        },
                      ],
                  }

Here under the examples field we can list one or more examples. As you can see, this works by including the literal response JSON in the spec.

(Fun fact: JSON is actually valid YAML.)

You can define multiple examples for a single status to illustrate different use cases or scenarios. In the above example we only have one example: the terribly named foo example. But you could instead of have properly named examples that describe the different cases in your domain.

Authentication

Finally, let's talk about authentication. We previously mentioned that API authentication usually happens with header parameters. But because there are more complex authentication mechanisms, and since authentication is core to almost every API available, OpenAPI has specific methods for describing how to authenticate against your API.

In OpenAPI's terminology, these methods are called security schemes. They define the authentication process for your API. There are 4 types of security schemes:

Basic Authentication
API Keys / JWT Bearer Token
OAuth2
OpenID Connect

We won't go into the specifics of these schemes in this post. I will just mention that security schemes also support the description field. Some of these authentication mechanism can be complicated and require multiple steps to configure. It is usually a good idea to refer to a longer tutorial in your description that you have written outside of the OpenAPI spec itself.

Authentication is often the first thing a new user has to deal with in order to get started with an API, so having solid documentation in this area is worth it.

OAuth2 Scopes

One thing to mention around operations is OAuth2 scopes. OAuth2 supports the concept of "scopes", which are similar to permissions around what the user can do once authenticated.

OpenAPI operations can specify which scopes they require in order to be called. If the authenticated caller does not have the required scopes, the operation should return an error and not give the called access.

Here's a brief example:

# First we define an OAuth2 security scheme
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access
            admin: Grants access to admin operations

paths:
  /billing_info: # Only admins can view billing info
    get:
      summary: Gets the account billing info
      security:
        - OAuth2: [admin] # <- Note the required admin scope
      responses:
        "200":
          description: OK
        "401":
          description: Not authenticated
        "403":
          description: Access token does not have the required scope
  /ping:
    get:
      summary: Checks if the server is running
      security: [] # <- No scopes required. Everyone can access
      responses:
        "200":
          description: Server is up and running
        default:
          description: Something is wrong

The scopes are defined as part of the OAuth2 security scheme. Each scope can have an associated description, which you should use to describe the purpose of the scope.

Note the descriptive error statuses for the /billing_info operation. If your authentication token is missing, or you don't have the required scopes, you get an appropriate error.

Conclusions

OpenAPI is a fairly complicated specification, but it can be incredibly powerful for documenting your REST APIs.

Key points to remember when working with OpenAPI include:

Understanding what goes into calling an operation

It's important to know what is required in to invoke the operations in your API: how to authenticate against it, and what parameters to provide.

These need to be made clear in your documentation.

Using description and summary fields effectively

This will let your documentation generator produce effective and readable documentation sites. Also consider linking to longer explanations from your description fields when required.

Providing real examples for request bodies and responses

Nothing beats a real example. Even better if you can provide your user an example that they can copy-paste into their terminal to start playing around.

Using HTTP correctly and returning approriate errors

HTTP itself can be quite descriptive. Work with the engineers designing the API to make sure you are using status codes and error messages effectively.

Selling to Developers: Your Documentation Is a Competitive Advantage

Nik Begley — Mon, 27 Feb 2023 12:33:23 +0000

Usually people think of technical documentation as helping existing users. Documentation lets customers find answers to questions themselves. It reduces load on your support team. But when you are selling to developers, your technical documentation is a sales tool.

Your ability to win customers will depend on how developers perceive your documentation, and thus your product. Bad documentation leads to lost sales. But great documentation can make you stand out in the market and help you win over developers and close deals.

Don't make me talk to a human

Developers have become an important buyer in modern tech organisations. Unlike many other buyers, the customer journey software engineers take is self-serve. This means:

They do not want to talk to a sales person
They want to try it before they buy it

In one survey, 57% of developers said they wouldn't reach out for a sales demo ¹.

Looking at the best companies that sell to developers, they make it easy for customers to buy how they want. 89% of developer-first Cloud 100 companies offer a freemium product or a free trial ¹

They give their prospects the ability to try out their product and form an opinion themselves. This is where your documentation comes in.

Building trust

Documentation builds trust with developers. If they buy your product, they will be spending hours or even months interacting with your service/API/SDK. Good documentation reassures developers. It lets them know they will not have to contact a support agent when they have an issue or something is unclear in your product. It is also an indirect sign of your product quality. If your documentation is sub-par, is your product that good either? ²

Stripe is the canonical example of a company with world-class technical documentation. So much so, that it has almost become a meme at this point. Every developer-tools company wants to have docs like Stripe. Their whole brand of being developer-friendly is built upon excellent documentation (and a product to match, of course). Building a payments integration can be hard. But they know that Stripe is a solid service that will guide them through the process.

If your documentation is unclear, hard to read, full of obvious mistakes or outdated screenshots, developers will turn away.

Guiding towards the "Aha-moment"

Another key function of your documentation is guiding developers on how to get started. It is important to help your users get to the point in your product where they have the "aha-moment" where they understand the value you can provide.

For any even slightly complex product, it is hard to get your users to this point through only an onboarding flow. You need tutorials and guides that help new users navigate your product.

In other words, you need good docs.

Docs are like air. It's impossible for a developer to be successful without them

- Andrew Baker, Twilio Director of Developer Education ³

Twilio is another company that prides itself on having high quality documentation. They provide "Quickstart" guides to introduce developers to various parts of their product. They have goal-based tutorials that walk through real examples of building a full Twilio-integration for different use cases.

Everything is pushing a developer new to the platform towards success.

Docs in sales

When I said developers never want to talk to salespeople, this is only partly true. Large enterprises with a complex list of requirements will still expect to talk to a human. But only after their developers have first developed an understanding of your offering on their own.

Even Atlassian, which at times claimed to have no sales staff, does sales:

If you're a large enterprise customer that has more complexity, or
potentially more value to us, we have a team that can help steer you in the
right direction and answer a more complicated set of questions that you have.

- Jay Simmons, Atlassian President ⁴

Our customers tell us documentation is something their sales representatives reference constantly on calls. We have even heard of companies giving early access to feature documentation privately to some customers, before releasing the feature publicly.

Documentation helps close deals.

Wrapping up

If you are selling to developers, your documentation has to be a high priority. Developers want to try out products themselves, and you have to be able to support them with proper guides, tutorials, and references. Having world-class documentation will make you stand out in the market.

Here are a few takeaways about how to improve your docs:

Make sure someone is responsible for the quality of your documentation
Have proper analytics to measure how people are consuming your documentation
Consider docs-as-code if you want your developers to be able to contribute to docs easily

What is OpenAPI? Examples, Purpose & Advantages

Nik Begley — Wed, 22 Feb 2023 13:37:40 +0000

OpenAPI, previously known as "Swagger", is a specification for describing HTTP APIs. Since its initial release in 2011, it has become a commonly adopted tool for companies to generate documentation and client implementations for their endpoints.

In this post we will go over how it works, some examples, and the advantages (and disadvantages) of using it.

The very basics

When you encounter an OpenAPI spec, it is either in JSON or Yaml format. I will look something like this condensed example from OpenAPI's own docs:

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [{ "url": "http://petstore.swagger.io/v1" }],
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        /* Removed for brevity */
      },
      "post": {
        "summary": "Create a pet",
        /* Removed for brevity */
      }
    },
    "/pets/{petId}": {
      "get": {
        "summary": "Info for a specific pet",
        /* Removed for brevity */
    }
  }
}

What this example describes is a "PetStore" API. It is accessible at the domain http://petstore.swagger.io/v1, it is currently at version 1.0.0, and it exposes 2 URL paths:

/pets
/pets/{petId}

The first path, pets, handles 2 different HTTP methods: GET and POST. The first lists all the available pets, and the second one creates a new pet (a very strange API, we will admit).

The second path only responds to the GET HTTP method, in which case it returns information about a specific pet, and it expects the URL to include the ID of the pet you are asking for.

For brevity, I have removed some details from this example. But you can see the the whole spec here. In it, you can see that the spec goes into detail about what the shape of the data it returns is, what errors can be occur, and much more.

This, in short is what OpenAPI is: a format for describing your API down to the smallest detail.

What is it used for?

There are 2 main uses for using OpenAPI:

Documenting and communicating to your users how your API works
Automatically generating code that can interact with your API

Documentation

Since an OpenAPI spec tells you exactly how your API works, we can use it to generate nice looking and easy to read documentation.

This is in fact what Doctave does - you can include your OpenAPI description and Doctave generates documentation automatically from your spec. Here is an example where GitHub's OpenAPI spec is rendered in Doctave.

This can be incredibly useful for your colleagues that may be writing code against an API you have designed, or customers using your product.

There are a whole host of OpenAPI tools ranging from documentation to code generation to linting and validating your specs. It is worth browsing around to see what is out there.

Generating API clients

In theory, if we have a well documented API, and know all the types in the responses as well as the available operations, we should be able to write a program that generates another program that can be used to interact with the API in question.

This is where the OpenAPI Generator tool comes in. It is able to generate client code in over 50 languages just by providing it an OpenAPI specification.

It goes even further and is able to generate server stubs that you can use as a starting point for generating a compliant service implementing an API contract.

Creating OpenAPI specifications

How does one go about creating an OpenAPI spec in the first place? How do you get that JSON or Yaml file that describes your API? You have two options:

1. Generate it automatically from your server code

There are tools that will look at the code running on your server and create an OpenAPI file based on it. This can be a great way to get started.

2. Craft it by hand

If you need more control, you can write the spec by hand. You don't have to do it all in your text editor though - there are visual and even collaborative tools for managing your OpenAPI specs.

There is no real right or wrong answer about which way is correct, but here are some arguments for and against both:

Auto generation

✅ Your spec will always be up to date
✅ Can sometimes require very little work from developers to set up
❌ It can be easy to accidentally introduce breaking changes

Crafting by hand

✅ Forces you to think carefully about API changes
❌ Can be more work (can be assisted by proper tooling)
❌ You have to ensure your server is compatible with your spec yourself

As a general rule, if you are descrbing an API that is consumed internally by others in your company, auto generating your specification can be a quick way to describe your API.

However if your customers are using your API, you need to be much more deliberate with breaking changes and API design over all. In this case, hand crafting your spec and running tests that ensure your service is compliant can be a better option.

Advantages and disadvantages of OpenAPI

Communicating how your API works is a hard requirement for anyone to actually use it. This is the problem OpenAPI tries to solve.

The big benefit of OpenAPI is that it is a standard. There is a large set of tools that know the format and having an OpenAPI spec lets you and your users take advantage of those tools. Documentation, client generation, and much more become easier once you have a well specified API.

But as the saying goes, there is no free lunch. So what are some issues with OpenAPI that we should be aware or?

1. Auto generation is not enough

You would be wrong to think that generating your OpenAPI spec from your server code is enough documentation for your users to get started.

This is why many sections in the OpenAPI spec include a description field which according to the spec can include Markdown. The designers of OpenAPI understood that examples must have written guides and examples to make the spec useful and gave authors the ability to add written prose to guide their users.

This means you will have have to spend time adding explanations in your spec, even if you auto generate a lot of it. This is less of an issue with OpenAPI itself, but something you should keep in mind.

2. You need to provide a lot of detail

It is easy to underestimate the amount of work that goes into describing your API. If you look at the screenshot above, the operation has a lot of detail: default values for parameters, example responses, a hand-written description.

Doing this for all of your operations is not a small task and you likely will not get the level of detail you need from just auto generating things from code. You will have to spend time annotating your code to give OpenAPI high quality hints about how your API works.

3. Some languages are not well supported

If you are using a slightly more esoteric language, do not expect client code generation or producing OpenAPI specs from your servers to work flawlessly.

Java, Go, Python, Ruby, JavaScript, and other "big" languages have well tested integrations, but your mileage may vary.

4. Not a great fit for event-driven architectures

If your API uses asynchronous messages heavily, OpenAPI does not provide great primitives for describing them.

Instead, you should consider looking into AsyncAPI, which grew out of OpenAPI to address this shortcoming.

Ultimately OpenAPI has proved itself to be a valuable tool by becoming the industry standard for describing HTTP APIs. It is a great tool that does its job very well when used correctly.

Why we built a Rust-powered desktop app for previewing documentation

Nik Begley — Thu, 02 Feb 2023 14:25:36 +0000

This post was originally published on the Doctave blog.

We took the arguably unusual choice to build a desktop app for documentation. If you look around, documentation tools generally fall in 2 categories: open source CLI tools, and cloud-based WYSIWYG editors. In this post we'll talk about the reasoning that lead us to build a desktop app instead, and how it actually works.

What is it for?

Our desktop app allows users to preview what their documentation will look like once published. It also catches errors such as broken links or syntactical problems.

Users can open our app next to their editor of choice, edit their Markdown documents, and the app will refresh on every save to reflect the latest version.

When an error is detected, the user is immediately notified, and clicking on the link in the error takes you to the page with the issue.

While my opinion is obviously biased, this fast feedback loop is amazing to work in. It takes the app milliseconds to do a complete re-render of the project, so you're able to move essentially as fast as you type.

Why a desktop app?

Doctave is built with
docs-as-code
in mind. As said above, there are two popular approaches for documentation tools: CLIs and cloud-based WYSIWYG editors. The point of docs-as-code is working on local files in source control so the cloud was out immediately.

So this leaves the CLI option. There's nothing "technically" that would have stopped Doctave from having this interface:

$ doctave serve .
Serving your docs at http://localhost:9090
...

But here are the negatives for requiring a CLI.

Better UX

There has been a resurgence of desktop applications in the past few years. This is likely partly due to technologies like Electron making it easier to ship applications built with web technologies as cross-platform desktop apps, but it's also arguably
because the user experience can be better.

Our users love that the preview and error checking happen in one place. You don't have to spin up terminal sessions and swap between an editor, a terminal, and a browser.

Also, our app is fast. We are using Tauri for the shell of our app and the business logic that compiles your documentation is written in Rust. It runs natively inside Tauri, and not in the browser environment (more on this below). This is how we can get such fast response times: we run native code instead of a bundle of JavaScript or even WebAssembly. Would it be possible to do this in a CLI? Yes, but the desktop app gives us a great environment to take advantage both native code and web technologies.

Finally, updates become trivial. Tauri's built-in update function has worked flawlessly, across 3 operating systems, ensuring our users have the latest and greatest version with minimal headache. You get a pop-up every time there's a new version, and the update happens automatically. There isn't really a universal way to update CLIs.

Non-developer users

A lot of people working with technical documentation are not developers themselves. They are still technical, but in roles like tech writers, product managers, or support agents. They are comfortable on the command line, can use Git, but do not want to spend time understanding why their version of OpenSSL does not match what is expected.

If you are expecting your users to setup a complex development environment to run your tool, you are alienating this important group of users. Even developers get frustrated when small environment differences cause npm install to fail!

There are ways to mitigate this, such as building static binaries. But you still have the problem of getting your users to update your SDK when you release features, you have to support different package managers, you have to make sure your software is not flagged by the OS as malicious, and much more.

A common comment we hear from our users: it's just easier to use Doctave.

How does it work?

As mentioned above, Doctave uses Tauri as the shell of our application. Think of it as a lightweight and security-focused Electron. It's a very interesting project that I highly recommend checking out. For our purposes, here are the 2 key features that are interesting:

It uses each operating system's native web view, making app bundles significantly smaller
You can code your local "backend" in Rust which you can invoke from inside the web view

(NOTE: this is not a "web server backend". This is code running natively
inside the local Tauri process.)

Doctave's core documentation project parsing code is written in Rust and we call it libdoctave. It takes as input a bunch of files and creates an in-memory structure that you can use to render a Doctave documentation site. It is used both in the desktop app and on our web platform, written in Elixir, via Rustler.

This is how we are able to share code across the desktop and the web platform. We can render the same content identically regardless of where we are.

Rendering a page

As an example, let's walk through what happens when Doctave renders a page you are editing.

First, Doctave is running a thread inside our local "backend" that is monitoring filesystem events. If it detects a change, it triggers a refresh of the project. Here's how that works:

The backend re-reads all the project files from disk
It feeds those files to libdoctave to create an in-memory representation of the project
libdoctave first runs a build stage, to check the project is syntactically correct
libdoctave next runs a verify stage, where all pages are checked for issues
Finally, the requested page's HTML is serialized and sent to the frontend to display, along with any errors

This all happens in single-digit milliseconds every time you edit a file.

As you can see, there is still a lot of room for optimization if ever required. We could be smarter about incrementally updating the libdoctave in-memory representation. We could reduce IO by only reading the files that have changed.

So far, however, that has not been necessary.

Desktop apps rock 🤘

Betting on Tauri and having a desktop app in general has been a great decision. Especially with our choices of technologies, namely Rust, this combination has been a delightful if somewhat unconventional tech stack.

Every startup has a certain number of "innovation tokens" that you can use on risky and/or new technologies. In our case, this was a great investment.

Wikis don't work for software documentation

Nik Begley — Tue, 21 Sep 2021 13:57:03 +0000

If your software documentation lives in a Wiki, it's very likely out of date and possibly actively harming your engineering team's productivity. This is a story that repeats in almost every organization - a tool like Confluence or Notion is selected as the "corporate knowledge base" of choice and developers start documenting code in them. But time and again that documentation goes stale and eventually serves no other purpose than to confuse eager new hires.

What are wikis good for?

First, let's take a look at what wikis do work for. They are used actively by millions of people every day and absolutely have good use cases.

We'd list the following reasons:

Trivially easy to add new content
WYSIWYG editing allows non-technical users to collaborate
Searchability and linking across pages

Wikis are an accessible and easy to use way to write down information. At a click of a button you can create a new page and the powerful in-built editors make it easy to add graphs and style to your thoughts. Finally, once it's all written down, you can reference other pages and search across the whole knowledge base. Wikis are the lowest common denominator that can work in most cases.

What can't you do with wikis?

But let's look at what you cannot do with wikis:

Integrate documentation changes into code review
Atomic changes to your docs and code
Programmatically generate docs at build time
Edit the documentation using your IDE/editor of choice

Wouldn't you want to be able to see during code review that the relevant documentation has been updated along with the code? Maybe the committer included a link to the updated wiki page, but are the docs changes already live before the PR is merged? Or will they remember to go submit the changes in the wiki once the code goes live? What if your update only applies to v2.5 of your product but not the newest v3.1 release and the documentation needs an important update?

None of these questions have clear answers when using a wiki and most likely will lead to the documentation simply never being written or maintained.

As Riona MacNamara, who worked on Google's internal documentation tooling, put it:

Documentation will never be part of engineering culture until it is integrated into the codebase
and workflow.

A better tool for the job

We previously wrote about how Google, Twitter, and Spotify all built their own docs-as-code systems for managing internal technical documentation. They did not build wikis.

Instead, they built systems that allowed documentation to live next to source code and get rendered into searchable pages in CI/CD. This practice is generally called "docs-as-code" and is not a new invention.

What they all found was that allowing developers to update documentation as part of their regular workflow lowered the barrier to update docs and ultimately lead to better documented projects. Instead of having to step into a different system to make changes to the project docs, all they had to do was open a Markdown file and start writing. There was one way to document and it was optimized for developers.

Removing friction leads to better documentation. We should be using better tools to remove all the friction we can.

Trade-offs

No solution is perfect, so let's take a moment to talk about the trade-offs of taking a docs-as-code approach.

Firstly, using docs-as-code will make it more difficult for non-technical collaborators to edit documentation. That being said, for internal technical documentation the maintainers should be the engineers and technical writers. Also, GitHub allows editing directly in the browser, so everyone does not need to learn the correct git incantations to contribute.

Secondly, you have to think about search. If you use a documentation site generator to turn your Markdown docs into HTML sites, even if the toolchain builds a search index for the site, you will end up with N disconnected sites for N projects. Doctave.com can help with this if you are using our open source documentation site generator.

Finally, your documentation will have to be limited to Markdown (or an equivalent format). Many would argue that this is a feature, not a limitation - forcing documentation to be in a simple format can make it easier to write and consume. Some tools will support useful "extensions" to Markdown. Our generator for example supports Mermaid JS diagrams, so that you can embed graphs and charts into your docs easily.

Technology options

Here's a quick list of some technology options if you want to look into docs-as-code.

We are building Doctave.com to be the best home for your technical documentation. If you want to do docs-as-code with a light-weight open source docs site generator, but host the docs in a centralized place that allows searching across all your projects, check us out.

There are also many open source generators out there that are worth mentioning: MkDocs and Docusaurus to name a couple popular ones. If you need something more customizable, Jekyll and Hugo are good options. Generic static site generators however tend to add a lot of complexity so we'd recommend going for something more light-weight.

In the end, the exact technology choice is less important. As long as it's not a wiki.

Doctave CLI 0.2.0: A Benchmarking Story

Nik Begley — Wed, 15 Sep 2021 12:34:15 +0000

The Doctave CLI is a free to use open source documentation generator. It takes your Markdown files and converts them into a beautiful documentation site. Today we have released version 0.2.0, which brings some cosmetic improvements and a fully in-memory development server for local development. We'll also talk about how this surprisingly did not make the CLI faster like we expected.

Serving your docs from memory

Before Doctave would rewrite the whole documentation site to disk every time you made a change to your Markdown files. It would pretty much rm -r the site directory, used to house the generated HTML, and regenerate the docs site from scratch. Because Doctave (which is written in Rust) is able to generate the whole site in ~tens of milliseconds, we hadn't looked into optimizations here yet.

But there were two non-performance related issues that bothered us about this approach:

You would end up with a site directory that didn't really serve any purpose while developing your docs
While very minor in scale in our case, constantly writing and deleting small files from disk isn't something that modern SSDs like to do

This is why Doctave 0.2.0 never writes the HTML documentation site to disk until you run
doctave build --release. In serve mode when you write your documentation, the embedded web server serves them directly from memory.

$ doctave serve Doctave | Serve Starting development server...

Server running on http://0.0.0.0:4001/

    File docs/README.md updated.
    Site rebuilt in 31.698781ms

Wait a minute - shouldn't this be faster now that we are not writing files to disk?

Why is this not faster?

After completing this feature, I was surprised to see that Doctave wasn't generating sites noticeably faster than before. I was expecting a speedup due to us not spending as much time on IO. This was not happening.

After double checking to make sure the code was doing what I expected, it was time to benchmark things to see where the time was being spent. After some digging I found the answer: generating the search index.

Doctave comes with offline search built in. We use the elasticlunr-rs crate to generate a search index that is compatible with the elasticlunr.js library. You can see it in action by going to our docs (built with the CLI, naturally) and hitting the letter s on your keyboard to focus on the search bar. The searching happens entirely client-side.

It turned out that we are spending ~70% of the site generation time creating the search index. This is completely reasonable, as this is a somewhat CPU intensive task that parses the input files and generates the index. The time spent doing IO writing files to disk is completely negligible in comparison, and thus did not move the needle much at all. On top of that, the CLI was already writing files to disk in parallel. Moving things in-memory did not save us much time.

So while Doctave 0.2.0 is technically faster, this was not a big performance win. There is some more work we can do to parallelize the build process further - maybe in the next release. In the meantime, Doctave will be more friendly on your SSD and not pollute your workspace as much.

Still, this was a change for the better. It just wasn't the big performance win I suspected.

Conclusions

I think this was an instructive little story about performance and benchmarking that was worth sharing. It's often the case that when we make assumptions about the performance of a system that turn out to be wrong once you measure things. This is just another reminder: always measure.

Finally, do try out Doctave 0.2.0! If you're looking for a batteries-included documentation generator that doesn't require plugins, doesn't pollute your repository with loads of files, and doesn't need a specialized environment to run, Doctave may be a good choice for you. It also comes with Mermaid JS diagram support and dark mode!

You can host sites generated by Doctave on GitHub pages, or your favorite static site hosting provider. We are also building a specialized host for teams using Doctave on multiple projects - check it out if you're using Doctave at your organization.

Let me know if you're using it to document your project. I can be reached at nik@doctave.com. I'd be excited to hear what you think.

Want to try out Doctave?

If you're on Mac using Homebrew, you can install Doctave with the following command:

brew install doctave/doctave/doctave

If you're a Rust fan and want to use Cargo, you can do so too:

cargo install --git https://github.com/Doctave/doctave --tag 0.2.0

We also have prebuilt static binaries for Mac, Linux, and Windows.

Why documentation is important

Nik Begley — Thu, 09 Sep 2021 11:23:37 +0000

Most software engineers know that they should write documentation. But how many can articulate exactly why documentation is needed? Let's look into some of the reasons.

1. Productive engineers

The lack of good documentation is often cited by engineers as one of the main reasons holding them back doing good work. In 2014, 48% of Google engineers cited bad docs as #1 productivity issue, and the 2016 StackOverflow survey found that poor documentation was the #2 challenge at work for engineers

Engineers are not cheap. If you have 100 engineers, and you save them them 1 hour each month because you have decent documentation covering your internal systems, that translates into huge savings and a sizable productivity boost. If your engineers are wasting time searching for answers to questions that have already been answered, your velocity is going to suffer.

If however engineers document their work as they go, a lot of these interruptions can be minimized. Instead of asking coworkers for assistance, just check the docs. Need to setup a new development environment? Just check the docs. How do I deploy this project again? Just check the docs.

2. Remote employees will thank you

Over the past 2 years thanks to the Covid-19 pandemic, evern more of us have had to become familiar with working remotely. The importance of documentation is emphasized when you don't have coworkers around to answer questions when you get stuck. Now, you have to rely on asynchronous communication channels to get your answer.

You may send an email to that senior colleague, but when will they respond? Maybe they'll be online in Slack, or are they on a different continent and fast asleep? You may not get your answer for many hours and meanwhile you're stuck, unable to make progres. What's worse, soon a significant portion of engineering time is spent in these communication channels coordinating work instead of in the editor.

Having high quality documentation allows your remote employees to help themselves to get the information they need without interrupting a colleague's workflow, and stay productive.

3. Onboarding becomes a lot easier

Bringing on a new engineer is a big investment. It often takes months for an engineer to ramp up and become productive in a new company - every codebase is different and requires some getting used to. During those months they will be asking a lot of questions and taking time from other engineers.

Having good documentation can help here. Instead of having to sit down with other engineers all the time, the new hires can read through the documentation and become familiar with the codebase and customs on their own. Of course they won't be able to become 100% productive on their own. But you will be able to cut down their training time. And your new hire will thank you because they can be self-sufficient and don't have to feel like they are constantly interrupting their new colleagues to ask questions.

This is actually a great opportunity to test your documentation. If a new hire can get started on a project on their own by reading the docs, that's a great sign. If not, figure out what is missing, and make the necessary changes. Just don't make the new hire change the docs - that's your job!

4. Stop the brain drain

Have you ever been in a company with that one engineer who has been there forever? The one that knows every single system inside out and people constantly come to them to ask about different parts of the codebase. These types of engineers can be a liability.

The "lottery factor" (also known as the "bus factor") refers to the number of team members you could lose before your business stops functioning. Having critical information inside the heads of a small number of key people means that you are at risk of losing important institutional knowledge if they were to leave after winning the lottery, getting a better job offer, or simply deciding to retire.

By building a culture where information is written down and documented you maximize your lottery factor and stop the brain drain.

5. Encourage transparency

Writing in public encourages transparency. It's empowering to be able to see what other teams are working on and break down silos in organizations. Especially with remote teams where you can't have watercooler conversations, writing things down is not only important but absolutely necessary.

Engineers can go and look at how other teams are solving problems and even suggest improvements. It's a great way to share knowledge and make sure information doesn't get stuck.

It's cheaper than you'd expect

One common complaint about documentation is that "we don't have time to write things down" or "documentation isn't necessary". These are similar objections to what automated testing encountered a decade or two ago. Today, testing is part of any project's definition of done.

Documentation does not take a lot of time if done incrementally throughout the software engineering lifecycle. Similar to how taking a project with 0% test coverage to >50% is a huge effort, if you start documenting a project with no existing documentation, it can seem daunting. But small incremental updates and refactors are a great return on time invested.

We've written a post about how Google, Twitter, and Spotify built their documentation cultures if you're looking for tips on how to improve your organization's documentation. Here are some quick ideas to get you started:

Use a docs-as-code approach to make it easier for developers to contribute documentation
Start asking for documentation updates as part of code review
Create "documentation days" where the whole engineering teams focuses on docs to bootstrap your projects with bad docs
Provide templates your teams can use as starting points to start documenting projects