IDA Documentation Strategy 1

Discussion: Sylvia Pearce (Deactivated), ClintonB (Deactivated), Renzo Lucioni (Deactivated), Alison Hodges, Peter Desjardins (Deactivated), Carol Tong (Deactivated), Joel Barciauskas (Deactivated)

There's been a bit of discussion about the best place to host documentation for edX IDAs. The current alternatives are to keep the IDA documentation for an IDA in the same repo as the IDA code or to add the documentation to the edx-documentation repo. This page is intended to help us hash out the pros and cons of each. Feel free to edit the page directly or add comments at the end.

edx-documentation repo

• All documentation is in one place, making it easy to find and update. There's no proliferation of documentation locations, all of which then have to be remembered.
• Documentation is branded, official, authoritative.
• Separate repos mean a lot of duplication. Also, if there are multiple copies of the same docs in different places, these docs could easily get out of sync. Docs for one or more IDAs may become inaccurate.
• Separate repos currently have separate readthedocs projects, making docs difficult to find.
• Doc team OKs the PRs that developers submit, leading to higher quality documentation.

Separate repos

• Docs are close to the code.
  • We can include information in readme files pointing users to the published docs, docs.edx.org, or the edx-documentation repo. Do users care where the documentation comes from, as long as they can find it?
• Some information in the docs is edx internal and shouldn't be available on readthedocs.
  • We need to think about who the audience is for the docs - what should be kept internal permanently, and what will start as internal but eventually be published for Open edX (e.g., the coupon admin tool)?
  • These docs are currently available on GitHub - is the credentials repo (for example) public?
  • Could we keep internal documentation in a separate folder in the edx-documentation repo, outside the built docs? 
• Joel Barciauskas (Deactivated) has said that docs are kept close to the code at other companies he's worked for. More information?
  • Joel The main point about keeping docs in the same repo is code is to tightly tie versions of code and documentation. "This version of the docs represents the functionality at this point of development", the same as with tests. Tests are typically tied much more closely to the implementation of code, so there's a stronger case, but the case is similar nonetheless.
• Developers maintain control of the docs.
  • Devs can update docs by making pull requests against the edx-documentation repo.
• Docs go out at the same time the code goes out.
  • This is our goal no matter where the docs are hosted.
• We could use readthedocs as an umbrella, then keep all of the IDAs in separate repos.
  • include directives may not work across repos, in which case we would still have the duplication problem. (Peter Desjardins (Deactivated) has said he thinks we can make the include directives work, though.)