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

• Developer vs User
• 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?
  • 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.
      
• 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.