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