Documentation Organization Discussion

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):

• http://docs.edx.org/ (Mix of User and Developer guides, Global and edX platform specific)

• Developer Documentation (new wiki homepage by @Andy Armstrong (Deactivated))

• Open edX Developer Documentation (Docs team wiki homepage)

  • Community Resources and Documentation

• Can we have a single top-level resource to point to?

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

• Architecture Communication Channels

Decisions:

• Google Docs should not be used for external communications

• GitHub wikis should not be used.