Documentation Bugs

Things that seem good:

Contribution documentation
- the CONTRIBUTING.md is kind of hidden, but I found it rapidly so it's not an issue. It may be worth the effort to add a CONTRIBUTING.md file to each repo like the one in edx-analytics-dashboard so the people could find it more easily
- the potential delays are documented and it appears that a guideline has to be respected by core commiter & product owner so that a contributor does not feel left alone in case his PR take some time to be reviewed

Needs:

code.edx.org does not point to issue tracking. It would be great to have a section explaining what is expected from reporters, explaining that they HAVE to sign in and pointing to
- (Archived) How to File a Quality Bug Report
- [Archived] Bug Categorization Guidelines
Add "use screen" instructions or equivalent 'cause it takes about an hour to run the installation script
Guide to debugging: not able to connect to CMS

Confusing things:

documentation does NOT indicate how to install the latest stable version, and go directly with the master one, which can break at anytime cause it's moving every day
There is the option to report issues on the configuration repo of edx. Is this intended or should one rather use JIRA?
Would it make sense to point out that bugs are to be reported in JIRA and other topics it the google groups?
Ubuntu 14.04 is not mentioned, some may wonder if they can take this route or not. 14.04 is also an LTS so it may make sense to support it as well
- I think I got it working with really small changes in the configuration repo, but 2G of RAM are way too small
Studio was giving a HTTP 500 error with a `ImportError: cannot import name OSRNG` error. I tried to upgrade `pycrypto` (the only "solution" that I can found on the internet), but it yields at me that it's already the latest version. After restart Studio, everything was fine...
- actually, it was working correctly when I did the installation from scratch a second time, it may be random :/

Installation (prod stack):

there is no documentation on how to split the different services on multiple servers
there is no documentation on how to enable HTTPS without using an SSL termination server
https://github.com/edx/configuration/wiki/edX-Production-Stack is an empty page
depending on the path from code.edx.org I choose, I will be presented different installation's options
- http://edx.readthedocs.org/projects/edx-installing-configuring-and-running/en/latest/ : that seems old and may be deprecated
- https://github.com/edx/configuration/wiki#installation-options : that page says that there are 4 options available, 1 of them is the Production Stack which is the empty page
- https://github.com/edx/edx-platform#installation : 3 available options on this one but 1 of them is the broken Production Stack :/
it may be useful to move the manual installation process from https://github.com/edx/configuration/wiki/edX-Ubuntu-12.04-64-bit-Installation cause there is some very useful information at the end of the page which seems to be part of the manual process. Maybe moving things is not the right answer, but we definitely need to make the last bit of information more easy to see

The page has not been updated for Aspen.

Installation (Dev stack):

when running the vagrant up for the devstack, the freetype error (which is documented so that's good) is not easy to spot. Indeed, it's written with the rest of the ansible output, in green (at least in my terminal setup). There are 2 parts that are printed in red so the first one seems to be the error but in reality, it's not an issue (at least it seems it's not) and one must really read the green stuff to see a its very end a message about freetype.
apparently the thread that further explains the MONGO auth temporary fix is no longer available or not properly linked. ( https://github.com/edx/configuration/wiki/edX-Developer-Stack)
the troubleshooting section in the github wiki, it´s really usefull. I would recommend to add some more links to it around because you might just miss it.
some additional troubleshooting tips may be required in relation to ruby ant the bundle install process.

Random Stuff:

In JIRA, there are issues which are links like "Original Issue (XZY-123)", which once clicked on go to a page asking for a log-in. The existing credentials used to create the account on JIRA does not work.

edx documentation:

There seems to be a broken reference in the read me page of the readthedocs documentation (http://edx.readthedocs.org/en/latest/read_me.html ) I suppose it should point you to https://github.com/edx/edx-documentation/tree/master/en_us/data/source

http://edx.readthedocs.org/en/latest/read_me.html

in the first page (readme) of the readthedocs project for building and running a course, (here) the first reference to the github repo for documentation is broken. (

https://github.com/edx/edx-platform/docs/en_us/course_authors/source)  probably due to the fact that they have moved part of the docs to an independent repo.  I guess the correct link would be: https://github.com/edx/edx-documentation/tree/master/en_us/course_authors/source

same thing for http://edx.readthedocs.org/projects/edx-installing-configuring-and-running/en/latest/read_me.html

OLX documentation:

the first link in the read me section for the OLX has an outdated link pointing to https://github.com/edx/edx-platform/docs/en_us/olx/source it should probably point to https://github.com/edx/edx-documentation/tree/master/en_us/olx/source
In the http://edx-open-learning-xml.readthedocs.org/en/latest/about/short-description.html page

it says : You create an HTML file called short_description.html in the overview directory.

it should say: You create an HTML file called short_description.html in the about directory.

in http://edx-open-learning-xml.readthedocs.org/en/latest/pages/pages.html#course-tabs is not clear enough that apart from writing html files for each new tab for the course, you have to edit the policy.json file to register your new tabs and also add in there something like:
,
"xml_attributes": {
"filename": [
"course/2014.xml",
"course/2014.xml"
]
there are a few missing example images in http://edx-open-learning-xml.readthedocs.org/en/latest/problem-xml/multiple_choice.html

Overall comments:

There are a number of similar tools being used in different places (github wiki, confluence wiki)