Re: [WWdevel] webwork documentation

[Sam H. <sh...@ma...>]

On 11/26/2007 10:56 AM, P. Gavin LaRose wrote:

> We now have an incomplete but growing block of documentation at
> <https://webwork.maa.org/moodle/mod/wiki/view.php?id=3D160>.  I've been=

> slowly expanding this in the course of this semester, mostly under the
> index of problem techniques section (at
> <https://webwork.maa.org/moodle/mod/wiki/view.php?id=3D160&page=3DProbl=
emTechniquesIndexByTopic>)
>=20
> This is obviously incomplete, and is also hobbled by being on the ugly
> Moodle Wiki.  I understand that Mike and Sam have MediaWiki running
> somewhere, and think that there's some global view for how all of the
> WeBWorK documentation will eventually reside on all of these things.
>=20
> My questions, which may be answered "yeah, something like that
> eventually" are (1) whether we can or should be moving the existing
> documentation over to a different site (e.g., the MediaWiki site), both=

> for ease of editing and for eventual unveiling. and (2) if so, whether
> the pages be moved transparently, without screwing up all of the links,=

> formatting, etc. Because it appeared too hard to figure out for Moodle'=
s
> Wiki I've been doing most of the formatting for the pages that I'm doin=
g
> in HTML, so it would be nice if that were preserved somehow.
>=20
> Just thinking aloud, in any case.

Hi Gavin (and other developers),

We do in fact have a wiki set up on webwork.maa.org at
<http://webwork.maa.org/wiki/>. It should recognize a Moodle cookie and
automatically log you in. (Initial login though the MediaWiki login page
isn't quite working yet, so log into Moodle first if necessary.)

I've been thinking about how to organize the new site, which will mostly
contain documentation. Here are my thoughts -- please give feedback!

Top-level categories:

* Installation, administration, and maintenance - Info for sysadmins on
how to install and manage WeBWorK.

* Using WeBWorK - How to use the WeBWorK web interface. Mostly for
instructors, since most of the complexity of WW is in the instructor
tools, but we would also want to have docs for students.

* Using PG - How to write and modify PG problems.

For now I'm focusing mostly on PG docs, since we've been doing a lot of
work on them lately and "modern" PG is the least discoverable aspect of
WW. So within the Using PG category, we'd have:

* Macro and library reference - This is what I'm currently working on.
It's represented as POD docs in the macro and library files in CVS. That
way, it's easy to keep it up-to-date and it's versioned along with the
code itself. (A web-based annotation system would be nice, but I think
it's more important to keep it "close" to the code.)

* Manuals and HOWTOs - Information on larger features of PG, like
MathObjects, or certain techniques, like the stuff you've been working on=
=2E

* "Best-practices" sample problems - Problems based on a "new" and
"non-crappy" blankProblem.pg, that feature MathObjects, don't use
deprecated techniques, and aren't the same trivial examples you always
see. These should be linked to from the other documentation where
appropriate, and should link back to the docs for the macros and
libraries they use.

As for moving pages over from the Moodle wiki... How many pages are we
talking about here? MediaWiki can handle raw HTML, so cut-and-paste
would work for the most part. As for links, I think we'll want to
replace real <a href=3D"..."> links with MediaWiki [...] links. If you
want to pawn the transition work off on me, go ahead -- I love mindless
busywork. :)
-sam