More documents for developers

More documents for developers

by Vu Hung -
Number of replies: 22

I posted this topic in Moodle Documentation course but there's no answers. Perhaps Moodle Documentation is only responsible for producing documents for teachers, students, and administrators (not for developers) smile. So I moved it to here.

At the moment, documents for developers is not enough. As a result, it's a bit difficult for new developers to customize and join the developer team. I used to work with PHP-Nuke. It's How-to document is very clear and detail.

Recently, some main Moodlers have discussed about generating API documents based on PHPDoc. It's very good idea. Besides these, we need more documents about the architecture of Moodle, relations among modules and lib, and about each module. You know the code of Moodle is getting bigger rapidly.

We can write helpful posts, articles (knowledge base) to guide new developers step-by-step to:

- Create a new module

- Create a new theme

- Create a new block

- Use important libs: data lib, web lib,..

- Put web editor in new module, new page

- Write secure code

- And more

That is my opinion. Any ideas?

Thanks,

Vu Hung

Average of ratings: -
In reply to Vu Hung

Re: More documents for developers

by Richard Crawford -
Vu,

I think you're spot on with this. We've had Moodle up and running around here since November, and I'm only now understanding how modules actually work (and let me just say that there's some incredibly clever stuff in there). And I've been using PHP for about five years, so I'm not inexperienced. The API documentation that I've seen has been somewhat useful, but there's a lot there that isn't well explained. I've spent many an hour pondering the functions in moodlelib.php and datalib.php just figuring out how to do these things.

We've established some in-house procedures for local Moodle development, and written a document (which we lovingly call the "Evil Monkey" protocol) which details this procedures, which are based on the development guidelines outlined elsewhere on the Moodle site. All of our local customizations are thoroughly documented, and our custom library of functions live in an entirely new lib file instead of being patched into one of the existing *lib.php files. Over the next few months, I'll be documenting our installation of Moodle thoroughly so that future developers here will be able to ramp up quickly.

Of course, by that time, the stable version of 1.5 will be out, 1.6 beta will be in development, and everything I've done so far will be obsolete. wink
Average of ratings: -
In reply to Richard Crawford

Re: More documents for developers

by Mawuli Kuivi -
I like this part

Of course, by that time, the stable version of 1.5 will be out, 1.6beta will be in development, and everything I've done so far will beobsolete. wink

Average of ratings: -
In reply to Vu Hung

Re: More documents for developers

by Martin Dougiamas -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers
It's difficult for me to find time, personally.

Volunteer technical writers (or funds to hire one!) are always welcome!!

The Documentation course is the right place, but it's just warming up and we have much basic documentation to clean up about installing Moodle and using Moodle first.
Average of ratings: -
In reply to Martin Dougiamas

Re: More documents for developers

by Dirk Herr-Hoyman -
Would it be ok to have a university course doing technical writing involved?
UW-Madison EPD 392 Writing User Manuals and Software Documentation.
I'm working with this them term,
they are using a tool we are developing as the basis for projects.
Average of ratings: -
In reply to Dirk Herr-Hoyman

Re: More documents for developers

by Martin Dougiamas -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers
It would be terrific!

Vu's list is pretty good.  I would add Themes and the other things on this page.  (Each section could be a document in it's own right).

All the content for the documentation is available either by looking in the source code itself or by searching these forums - it's just a matter of synthesizing all that.  I'm sure that questions or drafts posted in the Documentation forum would get a good response too.

It might be a good idea to use a Wiki to develop them ... the Developer Wiki in this course is a logical place.

Average of ratings: -
In reply to Martin Dougiamas

Re: More documents for developers

by Vu Hung -
I'm very pleased to write something but don't know where and how to start big grin.
Average of ratings: -
In reply to Martin Dougiamas

Re: More documents for developers

by Enrique Castro -
Picture of Core developers Picture of Particularly helpful Moodlers
Hi,
    David Rodriguez, the sysadmin at the ULPGC Moodle site has created some UML diagrams for Moodle. I am including a couple as an example;  he is working to complete the full Moodle functions.

Would those diagrams be useful for other developers? After upgrading for 1.5 improvements we could upload them to the Developers wiki, or mailed to you. Not being a professional developer, I cannot judge myself.

- Enrique -
Average of ratings: -
In reply to Enrique Castro

Re: More documents for developers

by Vu Hung -

Hi Enrique,

The UML-design is pro. It's a good example to follow. In my opinion, we should refer to Rational Unified Process, a good process to write documents.

Average of ratings: -
In reply to Enrique Castro

Re: More documents for developers

by Angel Villalba -

hola espero que puedas poner mas diagramas  porfa realmente los necesito

Average of ratings: -
In reply to Vu Hung

Re: More documents for developers

by Daryl Hawes -
I went through and added skeletal phpdoc comments in as many main libs and classes as I had time to with the hope that developers would see the format and choose to expand the comments that have todo tags and add comments to new functions as added. I also wrote a phpdoc guideline page which Martin has either not had time to review and post or has glaring problems smile
Please review the attached phpdoc guidelines page and comment or edit as applicable.

Daryl
Average of ratings: -
In reply to Vu Hung

Re: More documents for developers

by John Papaioannou -
<plug type="shameless">
I 'd like to pitch in here and say that for blocks there is this piece of documentation which I hope people will find useful even after 1.5 comes out. wink
</plug>

Astrid Sanchez from www.solearning.com has been kind enough to endure several updates to this document and still keep up with a spanish translation (final version pending); it would be nice to move both the original and the translation somewhere more obvious to developers, but I 'm not sure where exactly that would be.

Jon
Average of ratings: -
In reply to John Papaioannou

Re: More documents for developers

by Gustav W Delius -
Jon, I think your documentation for blocks developers is excellent. And it is in CVS which is where I believe all developer documentation should go. I would propose that in every directory for which we have documentation to add we create a subdirectory named 'doc' and place the documentation files in there. That will make it easy to find and distinguish the documentation files from ordinary files.

Now: could you write something similarly nice for your new table class? smile
Average of ratings: -
In reply to Gustav W Delius

Re: More documents for developers

by Vu Hung -

Hi Gustav,

I think quiz module is one of biggest modules smile. Do we have any documents for this module?

Cheers,

Vu Hung

Average of ratings: -
In reply to Vu Hung

Re: More documents for developers

by Gustav W Delius -
We made a start at explaining the new quiz module in the Developer Wiki but this needs to be updated, expanded and improved. Also I intend to move it into CVS. There is no particularly good reason why developer information should be in a wiki rather than in CVS. The versioning control of CVS is certainly better than that in the wiki.
Average of ratings: -
In reply to Gustav W Delius

Re: More documents for developers

by Martin Dougiamas -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers
Scattered through the CVS is not the best idea, because documentation writers may not be code writers. We also have to make it easier for translators if they want to translate them.

It will be much better to have it part of the main documentation project in one place, and possibly in a Wiki. More details on this soon because I'm just working with Przem on this.
Average of ratings: -
In reply to Martin Dougiamas

Re: More documents for developers

by Gustav W Delius -
Having all documentation in one place is a good idea but I think CVS would be a much better place for it than a wiki. Documentation often needs to be customized in the same way as code and the ability to merge in changes from CVS will be very important to keep the local documentation up-to date.

I think only a few very top-level documents in the developer documentation should be translated. If the detailed documents are translated then there is always the danger that the translation will be out of date and will mislead the developers.
Average of ratings: -
In reply to Gustav W Delius

Re: More documents for developers

by Martin Dougiamas -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers
We are probably just talking about two different levels ... I'm talking about more descriptive stuff like all the documents linked from this course currently, theme help, coding guides, API overview and so on. These will be centralised in a place where it's easy for technical writers to edit them.

If it's very technical stuff explaining, say, class structure for plugin questions and so on then sure, by all means keep it with the module itself (and keep it up to date along with the code!). (A lot of it should even be IN the code) We can link to these things from the main documentation anyway (as is being done now with the lang/xx/docs stuff from the documentation course).
Average of ratings: -
In reply to Vu Hung

Re: More documents for developers

by Vu Hung -

Hi all,

What about database design?

Some vital points are:

- Detail description about each table

- Relationships among tables

- Convention in naming fields and using types

- Approaches for multi-database solution

- And more...

Has anyone done something on it? Could you share it here?

Cheers,

Vu Hung

Average of ratings: -
In reply to Vu Hung

Re: More documents for developers

by Ravi Aranke -
Let me add that I have also been looking for this information.

I would love to be able to contribute to moodle in any way possible. I  intend to keep notes of my own bootstrapping (assuming it is successful and that I move beyond intention to actual contribution).

Also, what tools people have been using? IDEs, debuggers, scripts etc.

Thanks in advance,
Ravi
Average of ratings: -