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.