Documentation has to be updated
Opened this issue · 13 comments
There is no documentation or tutorial about the steps needed to reproduce the LTI interaction between the LMS and the Labmanager
Each repository on Github has it's own Wiki section. Should we use it? (It works with git, which is a nice feature for version management of the wiki)
If we're going to keep using the readthedocs, How do we update it?
readthedocs uses the sphinx documentation generator. Sphinx itself uses the reStructuredText format to generate documentation in html, pdf or other formats (mobi, etc.). You can find a lot of examples of documentation generated by sphinx: Python, flask (source), or ckan.
readthedocs only parses the github repository and generates the documentation offering the contents through a web page. You can even create an virtualenv etc. to add extensions, so it's quite cool.
The github wiki is fine (maybe for development), but in the case of WebLab-Deusto, it's the third time we change of wiki system (trac => Google Code => now sphinx), so I prefer using something that I can easily migrate to somewhere else.
I've been playing with sphinx today for WebLab-Deusto, and I'm more comfortable right now with it.
If we decide to use it as a "formal" documentation, where should we place the general documentation? Something explaining the global architecture, etc. Should we start with a new git project for that?
I have not started to document my part as I should, but le me ask you. Is there a way to tell Readthe docs to pull information from two separate git repos to create a documentation? or where will this documentation live?
I think that having the documentation on the same repository as the code is not a good idea. I would propose the wiki repository for this general information. This way it is 'within' the project but not on the same repository as the code.
Even if we don't use as a wiki, or even access it on github.
Well, in several projects I've seen (e.g. flask itself), it's in the same
repository (you download the correct doc with each tag). However, I'm fine
with putting it outside so the code repo is small. So, should we create a
lms4labs_doc repo?
readthedocs supports subprojects, but I haven't explored it yet.
Yes, that would be great.
(That will help me get started with some documentation I have to add)
Should we do an sketch of how the documentation should be managed, so we can create particular issues in that repository such as "document UNR RLMS", "document LTI bridge", etc.?
Fine, What do you have in mind?
We can discuss the table of contents. I've uploaded this one, feel free to modify or to add comments:
http://lms4labs.readthedocs.org/en/latest/
Once we have the table of contents more or less fixed, we can pass each header to an issue in that repo and start assigning them as we have time, and start adding contents.
One thing: what should we do with the documentation of each plug-in (RLMS, LMS)? For instance, it may make more sense to take the WebLab-Deusto RLMS plug-in documentation and put it in the rlms_weblabdeusto repo, and just link it from here. But that would mean having the doc and the code in the same repo. If you're more comfortable centralizing all the doc in the lms4labs_doc repo, I'm also fine with that.
That's a good point.
Since the rlms_* codebase is not that big, sounds good to have it within the same repo.
I think that the linking idea is a good way to go.
Sounds good. That way these plug-ins are even more decoupled (if somebody else wants to develop a new one, they can just create and maintain their own repo, add the doc and pass the URL).
What about the initial table of contents? Anything to change?