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