Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


The following are prompts for discussion. They are not final decisions.

Documentation Goals:

  • Easy to search (Google?  Confluence?)
  • Easy to find developer docs from code.
  • Easy to understand and answers questions.
  • Easy to write a new doc and know where it goes.
  • Easy to comment on or ask questions about?

Documentation home page(s):

Repository docs:

  • README should clearly point to relevant developer docs and/or the global developer doc home page.
  • API Docs
  • docs directory

Documentation dimensions:

  • Audience: Operator vs Developer vs User (Learner and Educator)
    • Operator and Developer guide dependent on the code.
  • Global vs Feature vs Repo

Additional Questions:

  • Differences between needs of small IDA vs edx-platform?
  • edx-platform:
    • What goes in the repo vs wiki vs readthedocs developer guide?
    • Can and should docs grow up from Confluence to RST?
      • Proposal that docs could start in Confluence, but should move to the repo when they are more "official".
    • edx-platform repo docs are a mess:
      • Global README and docs/README just point to read the docs
      • docs contains ini for help links
      • docs contain lots of old links and docs that probably would never be found.
      • Imports are breaking ability to publish docstrings using sphinx
  • OEP vs L'OEP (lightweight local OEP) or ADR (Architectural Decision Record, or OEP with minimal sections)
    • It was decided that this was not the highest priority.

Read the Docs accounts management

Communication channels


  • Google Docs should not be used for external communications
  • GitHub wikis should not be used.