OEP-19: Developer Documentation

OEP OEP-0019
Title Developer Documentation
Last Modified 2019-01-14
Authors Grant Goodman, Robert Raposa, Ned Batchelder, Nimisha Asthagiri
Arbiter Cali Stenson
Status Accepted
Type Best Practice
Created 2018-03-27
Review Period 2018-12-06 - 2019-01-11
_images/write.png

Context

Developers who work on the Open edX platform, both inside and outside of edX, need accurate and current documentation about platform architecture, APIs, and development best practices.

Developer documentation is defined as written specification, instructions, and resources for software developers who extend and contribute to the Open edX platform. It does not include documentation resources targeted for edX learners, educators, researchers, and Open edX operators. Those are out of scope of this OEP and maintained by the edX documentation team at docs.edx.org.

Developer documentation is inconsistent and poorly maintained. Documents are also difficult to find. They exist in multiple locations, including Read the Docs, GitHub repositories, Confluence wiki, and Google Docs.

This proposal focuses on long-term developer Documentation needs. It does not concern itself with any transitory Notes that a development team may use for project management, brainstorming, meeting notes, etc. Code Comments that a developer may add to clarify or rationalize a code segment are also out of scope of this OEP.

Note

The best practices and guidelines captured in this OEP are intended to be followed (for example, co-locating docs in GitHub, classifying different doc types, consolidating on formats). We have omitted considerations that we intend to experiment upon and capture in future edits of this OEP or other OEPs (for example, ownership responsibilities, API documentation details, choosing between writing ADRs versus OEPs, etc).

Decisions

A diagram that shows the different types of documentation and their relationships. This is further described below.

Agile Documentation Types

With Agile development and Clean Code, we can minimize documentation (and its maintainence) since code should be readable and self-documenting. However, for long-term maintainence of a platform, the following types of developer documentation are still needed:

OEPs

Description Open edX Proposals (OEPs) are a collection of system-wide technology decisions made by the Open edX community, in the form of best practices, architecture designs, and processes.
Answers the questions
  • What are the best practices and processes for developing on the Open edX platform?
  • How does system-wide framework X work on the Open edX platform? (e.g., Analytics, Authorization, etc).
  • Why was system-wide technology X or design Y chosen for the Open edX platform?
Rationale To establish software development coherency and efficiency with minimal centralized governance across a long-term maintained platform.
Location in GitHub Stored and reviewed in the open-edx-proposals GitHub repo; published to Open edX Proposals Read The Docs.
Maintainence OEP-1 describes the OEP review process. They will be maintained by the edX Architecture team.

ADRs

Description

Inspired by Nygard’s post, Architecture Decision Records (ADRs) are local lightweight documents of technical decisions co-located with their corresponding code. They provide rationale behind the code and the archeological path to their current state. The status of an ADR can be:

  • draft if the decision is still preliminary and in experimental phase
  • accepted once it is agreed upon
  • superseded with a reference to its replacement if a later ADR changes or reverses the decision

Note: Unlike code comments that focus on immediately surrounding code, ADRs provide the big picture context.

Answers the questions
  • What technical decisions were made for the component/feature in this repo/app/folder?
  • Why does this component/feature do X?
Rationale These records prove to be an invaluable technique for engineering teams to onboard new members, to understand discovered historical traces, to refer back to past decisions, and to support external oversight.
Location in GitHub A local decisions folder will be created within a docs folder in the repo/app/folder. The goal is to keep the decisions in as close proximity to the code as possible for their discovery and usage.
Maintainence Since ADRs are inherently a historical trail of technical decisions, by design, they do not need ongoing maintainence.

READMEs

Description READMEs provide a top-level summary and intentional purpose of the repo/app/folder.
Answers the questions
  • What is the responsibility and purpose of this component?
  • What are the terms and definitions of this component’s ubiquitous language?
  • How can I navigate the documentation within and related to this component?
Rationale The future evolution and development of a component remains within the intended boundaries of the component’s responsibility. Otherwise, it invites unintended complexity and incongruity.
Location in GitHub Since GitHub automatically renders the contents of the repo’s top-level README.rst file on the repo’s home page, README files will be located at the top-level of their corresponding repo/app/folder.
Maintainence The development team that owns the component should keep its README updated.

How-Tos

Description How-To documents provide relatively long-term step-by-step instructions in using a feature/component/etc. For instructions that are expected to be ephemeral and short-lived, other alternatives such as Etsy’s FYIs can be explored.
Answers the questions
  • How do I install/enable/use/test/etc this component?
Rationale To provide concise recipe-style instructions to users of the component so they can get started quickly without needing to understand the technical nuances and code of the component.
Location in GitHub A how_tos folder will be created within a docs folder in the repo/app/folder. The goal is to keep the How-Tos in synch with the code so that (1) developers running older versions of the code have the appropriately versioned information and (2) developers updating the component have easy access to update the corresponding How-Tos.
Maintainence The developer and code reviewer that updates the component will be responsible for updating the relevant How-Tos in that repo (preferably in the same PR as the code changes).

APIs

Description API documentation provide information on interfaces for integrating with or enhancing the platform.
Answers the questions
  • What are the public and supported APIs for this component?
  • What are the request/response/authentication/etc protocol for this component?
Rationale Developers that use and integrate with the component have a clearly defined and consistently documented interface.
Location and tools

The documentation of APIs should be automatically generated and extracted from the code and its annotations. For example:

  • REST API interfaces should be automatically generated using Swagger.
  • The Open edX Learning Exchange (OLX) format should be automatically generated.
  • Plugin interfaces (e.g., Proctoring integration) should be automatically generated using Sphinx.
  • Public APIs (e.g., supported Javascript libraries, supported Python APIs) should be automatically generated using Sphinx.
Maintainence Since they are automatically generated, API documentation do not need additional maintainence and will be in synch with their corresponding code.

Requirements

This section summarizes the requirements for long-term developer documentation.

  • Discoverable. Users must be able to find the documentation that is relevant to their needs. This calls for a high-level index and search mechanism for finding content.
    • Search. For the time-being, we will make use of Google and Github’s search functionality for finding content since all developer documentation will be in Github. Certain IDEs may also have tools for searching.
    • Index. In the future, we will invest time in a better automated indexing tool to aggregate and structure the documentation. For the time being, we will manually create and maintain documentation indices at:
      • edx-developer-docs will include the landing page for developer documentation and be a container of orphaned and cross-repo developer documentation.
      • docs.edx.org will be the main landing page for all Open edX documentation, including a link to the developer documentation index listed above.
  • Maintainable. Writers, editors, and reviewers must be able to create and modify documentation without too much effort.
    • Co-located. The closer the documentation lives with its corresponding code, the more likely it will be kept up-to-date.
      • For repo-specific documentation:
        • ADRs and How-Tos will live within docs folder(s) within the repo.
        • READMEs will be located as top-level documents in the repo/folder/app.
        • Documentation should not live within the code itself (e.g., in __init__.py modules).
      • For system-wide documentation:
    • Exported Diagrams. In order to keep diagrams updated across time, they will need to be exported from whichever tool they were created in, with the exported version maintained in Github.
      • draw.io diagrams will be exported and imported as XML files.
      • Lucidchart diagrams will be exported and imported as Visio (VDX) files.
  • Version Controlled. Documentation must be maintained under version control in Github, for the following reasons:
    • Reviewed. They will be properly reviewed as defined by that repo’s process. Anyone in the Open edX community with access to the repo will have the ability to add, update, fix, and contribute to documentation by following the repo’s review and maintainence process.
    • Tagged. They will be appropriately in-synch with their corresponding code. For example, when an open edX instance runs an older named release, the operator can refer to the matching documentation for that version of the codebase.
    • Source Controlled. They will have the advantages of having source-control backed files, including sharing across multiple developers and robust storage.

Format

We will use reStructuredText (rST) for all developer documentation.

  • rST scales up: it can be used for anything from docstrings to single-page documents to books to multi-volume book sets.
  • rST has a rich feature set, including inter-document links, table of contents, auto-collection of code documentation, list-formatted tables, semantic markup, and multiple output formats.
  • A single documentation format enables consistency. It also avoids conversion to rST when we require its additional features. Our experience has shown that these two benefits of standardization keep down the overall cost of documentation maintenance.
  • rST is the standard markup format for Python project documentation.
  • rST does not suffer from incompatible implementations, with different features supported differently by different renderers.
  • GitHub renders rST natively.

More details on these points are in Eric Holscher’s why rST over Markdown for documentation blog post.

Best practices

  • We strongly recommend that rST documents auto-wrap rather than have fixed line lengths (of 120, for example), for the following reasons:
    • Both GitHub and popular IDEs support rendering of auto-wrapped files.
    • Auto-wrapping allows renderers to be responsive, automatically format according to the reader’s view width, and better supports split-window mode of development.
    • Developers don’t need to spend time continually reformatting lines whenever they edit their documents in order to remain within fixed line length limits.
    • Although GitHub’s diff-ing capabilities are currently better when line breaks exist, this seeming advantage actually disappears when developers reformat lines in a paragraph to adjust to line length limits.
  • Consistency across rST documents is not a requirement. However, you can use the raw version of this OEP as a reference example.

Learning rST

Rejected alternatives

Markdown Format

We are choosing to not use Markdown (MD) for documentation. A single format enables consistency, and avoids conversions to rST when requiring additional features. See the Format section for more details. The Learning rST section has resources comparing Markdown and rST.

Confluence

Currently edX uses Confluence for storing both long-term and short-term developer documentation. Confluence does provide a WYSIWYG editor, which makes its relatively easy to create and edit documents. Its transitory nature also provides an impetus to rapidly writing down notes and thoughts. Given this, we do expect some hesitancy with transitioning to writing rST files in GitHub. However, as described in this OEP, GitHub provides the benefits of versioning, reviewing, release-tagging, and co-locating, which we expect will result in better quality and maintainence of our developer documentation.

Confluence Usage and Migration

We will continue to use Confluence for transitory and “edX private” documentation needs since it is already a hub of communication for both edX employees and the Open edX community. However, the long-term types of developer documentation listed in Agile Documentation Types will need to migrate to their new locations.

Migration

When migrating content from Confluence to GitHub, we will:

  1. Reformat it to rST and store it in the appropriate location in GitHub.
  2. Delete the content from the old page, with a forwarding link to the new Read The Docs location.
  3. Archive the old page, as explained below.

Archive

For sustainable maintainence of Confluence documents, ongoing cleanup will be implemented using Confluence’s useful Space Archive feature. All engineering related documents will be archived to the private Archive: Engineering space.

When a page is archived:

  • The page and its contents are no longer included in normal searches, thus keeping our search results decluttered.
  • The page no longer appears in Google searches.
  • Links to the old page are automatically forwarded to its new location in the Archived space (unless the old page’s containing space is entirely deleted).

You can search for archived pages using Confluence’s advanced search. From the Confluence search panel, select Advanced Search, then select Search archived spaces.

_images/confluence-archive-search.png

Index

Since we will continue to use Confluence for certain types of documents, we will maintain the following two top-level indices for engineering related documents:

Next Steps

  • Publishing: The intention is to have all rST documents published to Read the Docs.
  • Validation: The intention is to have all rST document changes in all repositories automatically validated as part of the Continuous Integration quality tests for any PR. See the edx-developer-docs repo or the cookiecutter-django-app repo for examples.
_images/quill.png