Documentation is missing lots of stuff
piehei opened this issue · 3 comments
Hi
We have multiple new teachers and TAs using this tool to build new courses. Some of the RST directives and their options are not covered in the documentation. For instance aplusmeta, which configures module deadlines, is not explained anywhere. You may find out about it if you look at this piece https://github.com/apluslms/course-templates/blob/master/m04_converting/02_chapter_workflow.rst but people creating something completely new instead of converting old stuff to this new format might just glance over it or skip it altogether (the documentation chapter is, after all, about convering old material to new format).
Could someone with knowledge of this tool update the README to cover all the directives and their options? Now you have to go to see the source to find about them (eg. how to make a module hidden is not documented anywhere, not in this repo or in course-templates repo).
I understand documentation work might not be the hottest thing one wishes to do but important altogether still. Eg. this issue https://github.com/Aalto-LeTech/a-plus-rst-tools/issues/26 was discussed in official a-plus Slack and no one remembered how the thing worked until every possible combination was tried out (in the beginning it was not clear if it was even implemented).
:)
Thanks!
I can maybe write something today.
That would be super nice!
What I'm looking for is the kind of a reference guide you've already got on the README of this project. The course-templates documentation is written so that you can grasp nicely what the heck the whole platform is, but it is not too easy for finding something quickly (eg: how to set late penalty). IMO the optimal format would be to just include all directives and their config values in the README.
I would structure it like so: what goes into conf.py (global(ish) config values like category names, default points etc. which currently you have to find out on your own), what goes into a module configuration, what goes into chapters/exercises, and finally, the different exercise types.
But any improvement is good of course!