Quiz

You are absolutely right that the question bank code needs better documentation. And it is brilliant that you want to write it. Let me just explain the documentation I would like to see, and why I think that is the right approach, then I am happy for you to proceed in the way that seems best to you.

What makes code difficult to document is that it always changes. That is good; It is progress; but we need to think about how we are going to handle that change when writing the documentation, so it remains useful with as little maintenance work as possible.

Code needs to be documented at three levels of detail. Starting with the most detailed and working up they are:


1. The code itself

Particularly in Open Source, the code is not just a way for the programmer to tell the computer what to do. It is a way for programmers to collaborate with each other. Other programmes must be able to look at it and follow what is going on, and understand how they would need to modify it to fix bugs or add new features.

In a world where the code is constantly changing, it is particularely good if the code can document itself, becuase that documentation will never be out of date.

When I say 'the code', I include the brief inline comments that are used to clarify the code, for example:

// Print each answer in a separate row

The code itself should answer the questions: 'how does this part work?'.


2. A description of each class, function, method, etc.

Next, for each function, method, global variable, class, etc. in the code, there should be a description of what it is for. This should mainly be from the point of view of someone who wants to use this function, but who does not necessarily need to know how it works internally.

This is the level of documentation that is likely to go out of date quickest, because it needs to be quite detailed. Therefore, most modern programming languages have a way of including this documentation inline. For PHP the system is called phpDocumentor. To use it, you add specially formatted comments in the code, just before the function (or whatever) that you are documenting. For example:

 /**
 * The name this question should appear as in the create new question
 * dropdown.
 *
 * @return mixed the desired string, or false to hide this question type in the menu.
 */
 function menu_name() { 

The idea is that since this documentation is stored right next to the code, this maximises the chance that it is kept up to date when the code is changed.

Of course, it does mean that the comments are spread throughout the code, which makes them difficult to browse. And that is the clever half of phpDocumentor. You can use it to scan the whole code, and automatically build a documentation web site like this one: http://phpdocs.moodle.org/ (which currently seems to be broken. Drat!. MDLSITE-153).

(So Pierre, my concern was that what you had started doing was to emulate phpDocumentor manually in the wiki.)

This level of detail answers the questions: 'How do I use the function? What data do I need to pass it? What will I get back?'


3. An overview of the whole system

This is the part that belongs on docs.moodle.org, and which is currently missing or badly out of date.

This gives a brief summary of the whole system, so you have some idea of where to start looking at the details. It explains some of the higher level concepts that are used, like database structure or in-memory structures, and any conventions or organising principles. It should also include getting started guides, or howtos.

There is a bit of this so far, but a lot of it is out of date or incomplete, and there are some big gaps. However, even though it is out of date, it is still suprisingly useful because it describes the general ideas on which the code is build, and these change more slowly than the details of the code.

http://docs.moodle.org/en/Development:Question_engine

This is the most general overview. I have not even read it recently, so I don't know how good or up-to-date it is.

http://docs.moodle.org/en/Development:Quiz_database_structure

The diagram a the top is up to date and quite useful. The text underneath is horribly dated, but is still useful if you can relate the old table names to the new ones in the diagram.

http://docs.moodle.org/en/Development:Quiz_state_diagrams

Another diagram that I hope is useful, but it really needs to be explained.

http://docs.moodle.org/en/Development:Question type plugin how to

A good start, but only about half written.


I think that the main missing pieces are:

A. A page describing the main in-memory structures that are used throughout the question-bank code. That is, the two different ways that $question objects are stored in memory, and the $session, $state and $cmoptions objects.

B. A page describing what an activity module needs to do to use the question types. That is, what functions it needs to call when. I am not sure anyone really knows. All the knowledge is implicit in the current quiz code. When Jamie and Peter write the question creation as a studnet activity module, they will have to work it out, and if we are nice to them, they may be able to add it to the docs.

C. A summary list of all the question type methods and roughtly what they are for, with links to the documentation on phpdocs.moodle.org.


This is just what I think, but I hope you agree that there is some logic to it, and that is a good approach to making it as easy as possible for people to work with the code.

Another key requirement for documentation, I think, is for it to be as short as possible. I don't at all mean that we should leave pieces out. What I mean is that if the code is well structured, it should be possible for people to use and understand it without having to read pages of documentation first. It should be enough to read about a few key concepts that have been explained clearly and succinctly, and they be ready to go. Also, the less text it takes to explain everything, the less there is to keep up to date.



[P.S. I used my powers as forum moderator to remove a message from me to Pierre and his reply, which I only posted here because emails were not getting through. I hope that is OK. Then I renamed this thread to better represent the substance of the discussion.

I'm afraid Pierre that the alternative email address you gave me also bounced. Do you think UQAM has put the OU on some sort of black-list?]