openwebwork-devel

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

Re: [WWdevel] webwork documentation

[Michael G. <ga...@ma...>]

Hi,

Thanks Sam for getting this started.

I put up a first page on the WeBWorK documentation wiki at

http://webwork.maa.org/wiki/Main_Page

responding more or less to your outline below.  I haven't created
any further pages yet -- (but go ahead and start if anyone has time).

The next page in each hierarchy would have a list of subtopics and  
below that for
the most part would be individual documents.

Do you think we should create navigation links in the left margin for  
each of the
main sections?

Let me know what you think.

Take care,

Mike
On Nov 29, 2007, at 4:32 PM, Sam Hathaway wrote:

> 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=160>.  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=160&page=ProblemTechniquesIndexByTopic>)
>>
>> 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.
>>
>> 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  
>> doing
>> in HTML, so it would be nice if that were preserved somehow.
>>
>> 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.
>
> * "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="..."> links with MediaWiki [...] links. If you
> want to pawn the transition work off on me, go ahead -- I love  
> mindless
> busywork. :)
> -sam
>
> ---------------------------------------------------------------------- 
> ---
> SF.Net email is sponsored by: The Future of Linux Business White Paper
> from Novell.  From the desktop to the data center, Linux is going
> mainstream.  Let it simplify your IT future.
> http://altfarm.mediaplex.com/ad/ck/ 
> 8857-50307-18918-4_______________________________________________
> OpenWeBWorK-Devel mailing list
> Ope...@li...
> https://lists.sf.net/lists/listinfo/openwebwork-devel

Re: [WWdevel] webwork documentation

[P. G. L. <gl...@um...>]

Hi Sam,

The current documentation on the AIM site includes some 20-35 pages, 
counting the code snippets that I've been working on.  I spent a bit of 
time seeing how easy it is to copy those over to the MediaWiki site, and 
it's non-trivial but not a disaster.  The biggest problem is that 
MoodleWiki thinks that WikiWords are automatically links (but MediaWiki 
doesn't seem to subscribe to this) and the links in the two are different.

In any event, I marked the section of the language documentation on the 
old site, <https://webwork.maa.org/moodle/mod/wiki/view.php?id=160>, as 
being moved to the MediaWiki site, and played with filling in pages at 
<http://webwork.maa.org/wiki/Writing_WeBWorK_questions>.  Basically I 
copied the top level pages to see how it works and stopped there.  If you 
want to copy the pages under the Index of Problem Techniques, at 
<https://webwork.maa.org/moodle/mod/wiki/view.php?id=160&page=ProblemTechniquesIndexByTopic>, 
that would be great.  Other than that there are only a couple of other 
pages that need to be moved across, and I suspect that some of those will 
want to be edited and reorganized.

I also need to learn how to attach files in MediaWiki.  For example, to 
<http://webwork.maa.org/wiki/SampleProblem1> et al.

Additional comments and suggestions welcome, of course.

Gavin

--
P Gavin LaRose, PhD | gl...@um... | 734.764.6454 or maybe 763.3249
Program Manager, Instructional Tech.    | ...you have to respect someone
Mathematics Dept.,  Univ. of Michigan   | who can spell Tuesday, even if
http://www.math.lsa.umich.edu/~glarose/ | they can't spell it right.
                                                                   -Milne


On 2007-11-29 [16:32] Sam Hathaway wrote:

> 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=160>.  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=160&page=ProblemTechniquesIndexByTopic>)
>>
>> 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.
>>
>> 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 doing
>> in HTML, so it would be nice if that were preserved somehow.
>>
>> 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.
>
> * "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="..."> links with MediaWiki [...] links. If you
> want to pawn the transition work off on me, go ahead -- I love mindless
> busywork. :)
> -sam
>
>