Subject: [LON-CAPA-dev] Help text

From: Guy Albertelli II <[email-masked]>
Date: Fri, 3 May 2002 17:20:12 -0400 (EDT)

Hi,

I wanted to create some webpages of help text to integrate into
LON-CAPA

do we have a directory for help webpages yet?

-- 
[email-masked]        BM: n^20 t20 z20 qS 
Guy Albertelli -7-8-7-  O-
    My personal happiness depends on the suffering of others.

---

From: Scott Harrison <[email-masked]>
Date: Fri, 03 May 2002 17:42:40 -0400

Dear Guy:

3 cans of worms here...

This is a brief synopsis of help screen effort.

worm-can #1: where in /home/httpd/html do the documents reside?
and where in CVS?

...currently the status is...
<file>
<source>loncom/html/adm/help/searchcat.html</source>
<target dist='default'>home/httpd/html/adm/help/searchcat.html</target>
<categoryname>interface file</categoryname>
<description>
Help page for the search engine.
</description>
</file>

worm-can #2: what do the help pages look like?
...currently the status is...

And the vision was that every help page have the following
template of beginning html code.

<body bgcolor='#ffffff'>
<a name='helptop' />
<img align='right' src='/adm/lonIcons/lonhelplogos.gif' />
<h1>Search Catalog</h1>
<hr />
<form>
<input type='button' onClick='self.close()' value='Close this help
window' />
</form>

worm-can #3: It would be nice to automagically construct
indexes of the help pages, not just for the interface, but
also for the underyling code documentation.
I do have some code which does this nicely for 
POD sets, but have yet to incorporate.

(Ideally, the interface help pages would streamline nicely
down the vertical partition toward the actual documented
code base.  But...priorities...priorities..)

Practically speaking... umm... searchcat.html is the only
online interface help page so far.

I remember a little debate and indecision regarding
creating httpd/html/adm/help versus
httpd/html/res/help versus httpd/html/help etc.

There was even the discussion and undecided issue as to
whether or not the public should be able to look at the
interface help screens.  Or, should only the LON-CAPA login
users see the help screens

So... to answer your question... kinda sorta yes
there are directories for help pages.

Regards,
Scott

Guy Albertelli II wrote:
> _______________________________________________
> LON-CAPA-dev mailing list
> [email-masked]
> http://mail.lon-capa.org/mailman/listinfo/lon-capa-dev

-- 
Scott Harrison -- Graduate Student
Microbiology and Molecular Genetics
Mich. State. Univ., East Lansing, MI
[email-masked], 517-353-0998

---

From: "Matthew Brian Hall" <[email-masked]>
Date: Thu, 9 May 2002 15:11:13 -0400 (EDT)

Scott, et al.

> worm-can #1: where in /home/httpd/html do the documents reside?

home/httpd/html/adm/help/ and loncom/html/adm/help/ make sense to me

><input type='button' onClick='self.close()' value='Close this help

This looks good.  However I do not like the lonhelplogos.gif.  I would
prefer to minimize the footprint of the help pages.  I envision people
having the pages open in a second (third, counting the remote) window
as they write problems.  A smaller (nonexistant?) icon would be nice.
Or a nifty header image.

>POD sets, but have yet to incorporate.

Well, I doubt there will be so many help pages at first that we cannot
easily add in any tags needed for indexing.  I think it is more valuable
at this time to actually have help pages.  What metadata do these pages
need to have in order to be indexed automagically?

I envision the pages being linked to in the problem editor.  See the
plot editing interface for my version.

>code base.  But...priorities...priorities..)
I have no idea what that means :)

>users see the help screens

Matthew

--
------------------------------------------------------------------
Matthew Hall           LON-CAPA developer         [email-masked]
123 North Kedzie Hall                    Michigan State University
------------------------------------------------------------------

---

From: Scott Harrison <[email-masked]>
Date: Thu, 09 May 2002 15:45:43 -0400

> need to have in order to be indexed automagically?

The only "metadata" would be title and hierarchy.
The target directory location would be the hierarchy... (maybe we don't
want a hierarchy, but anyways...) for instance:
+ Instructor Tools
  + Spreadsheet
  + Plotting equations
  + RAT
  + Class lists
+ General information
  + Remote control
  + Roles
  + Answering Problems

(And of course, this should be in sync ... and draw from ... 
 help.lon-capa.org).

And then, students may not want to be bothered with instructor
tools...

> I have no idea what that means :)

Pressman, Rumbaugh, etc; a lot of standard books on
software engineering talk about horizontal layers
and vertical partions.

Horizontal layers "make sense of the system".
That is to say, they are the levels of computer services
that exist.

For example,

---------- LON-CAPA web interface ------------------------
------------- Apache::* libraries ------------------------
---------------- mod_perl --------------------------------
----------------- apache ---------------------------------
-- shared libraries (including CPAN libraries) -----------
----------------- kernel ---------------------------------

Contrastingly, vertical partitions are how the software
design proceeds across the horizontal layers to provide
user services.

So, restated, ideally, there would be a clear path from each
LON-CAPA interface to the source code documentation
that was involved in presenting and processing information
from that interface.  

Testing might ask, horizontally:
* are all the kernel and shared libraries present that
  need to be present
* is the web server running in the right configuration?
* mod_perl, is it working?
* are all the CPAN libraries present?

Vertical partitions might ask, testing-wise,
is the metadata database interface working
and what is all the source code involved with it?

The testing strategy that I have been trying to find
time to implement is:

Horizontal layer testing in:
loncom/build/system_dependencies

Vertical partition testing in:
loncom/build/weblayer_test

Anecdotally...

    we are all part of the matrix. :)

The blue pill or the red pill?

Regards,
Scott

---

From: Gerd Kortemeyer <[email-masked]>
Date: Fri, 10 May 2002 10:01:51 -0400

Hmm ...

I actually had the following idea a little while ago:

We will put new headers on the admin pages anyway, so there will be a
header-producing routine in lonnet. It will look something like this:

$r->print(&Apache::lonnet::pageheader('Spreadsheet','grading'));

and puts up the correct role header. For "advanced" users, it also produces a
"Help" and a "Bug" link.

These do not go to a third all-new structure, but just go a the FAQ and
Bugzilla. There is a table in the system like this

grading    134    Instructor+Interface

which means that these links will go to

http://help.loncapa.org/fom/cache/134.html
http://bugs.lon-capa.org/buglist.cgi?component=Instructor+Interface

- Gerd.

---

From: Guy Albertelli II <[email-masked]>
Date: Fri, 10 May 2002 11:10:01 -0400 (EDT)

Hi Gerd,

> and puts up the correct role header. For "advanced" users, it also produces a

BUT this doesn't help the homework editor or other locations where a
more detailed specific help message would work better.

Like the plotting code does taoday, and I want to do something similar
owith the <script> environment and the list of functions.

-- 
[email-masked]        BM: n^20 t20 z20 qS 
Guy Albertelli -7-8-6-  O-
    The next time the universe knocks on my door, I will pretend I
    am not home.

---

From: Scott Harrison <[email-masked]>
Date: Fri, 10 May 2002 11:31:58 -0400

I was actually going to place myself inside lonnet since
everything else is there. :)

---

From: Mark Lucas <[email-masked]>
Date: Fri, 10 May 2002 11:42:09 -0400 (EDT)

I agree with Guy. There are cases such as the homework editor where more
focused help will be desired. If my instructors have to dive through the 
faq to find some of these details, frustration levels will be high.

						Mark

> owith the <script> environment and the list of functions.

----------------------------------------------------------------------------
Mark Lucas					email: [email-masked]
252D Clippinger Lab  				phone: (740)597-2984
Department of Physics and Astronomy             fax:   (740)593-0433
Ohio University
Athens, OH 45701

---

From: Gerd Kortemeyer <[email-masked]>
Date: Fri, 10 May 2002 11:58:06 -0400

Good idea! A built-in Scott would certainly enhance the system. I would suggest
that on the screen, you could manifest yourself as a paperclip - "It looks like
you are writing a randomlabel problem."

http://www.microsoft.com/Office/clippy/default.asp

Correction: put header routine in loncommon ... better?

Anyways, besides the special help on special stuff (you all convinced me!), does
the link to FAQ make any sense?

- Gerd.

---

From: Guy Albertelli II <[email-masked]>
Date: Fri, 10 May 2002 12:04:33 -0400 (EDT)

Hi Gerd,

> Anyways, besides the special help on special stuff (you all
> convinced me!), does the link to FAQ make any sense?

> > > http://bugs.lon-capa.org/buglist.cgi?component=Instructor+Interface

Pros
1) documentation can be corrected without the user updating the system

Cons
1) User must have a valid internet connection in order to get help
2) We can't reorganize things on the FOM without breaking everyone's
   install

-- 
[email-masked]        BM: n^20 t20 z20 qS 
Guy Albertelli -7-8-6-  O-
    I will strive to be godlike.  I will start by condemning my enemies
    to an eternal hell.

---

From: Gerd Kortemeyer <[email-masked]>
Date: Fri, 10 May 2002 12:22:52 -0400

Hmm ...

> 1) documentation can be corrected without the user updating the system

... and growing ...

> 1) User must have a valid internet connection in order to get help

Only an issue if you are running around with a standalone laptop, which is
both your client and your server.

> 2) We can't reorganize things on the FOM without breaking everyone's

Yep. At least not shuffle categories around. Alternative: maintain alias
links on help.lon-capa.org, for example

http://help.lon-capa.org/spreadsheet/

and put cache page number into httpd.conf.

I just want to make sure that we do not have to update and maintain too many
independent user help mechanisms.

BTW, the same mechanism could be used for the specific help. Put in the
specific help-item as an FAQ and link to it.

- Gerd.

---

From: Helen Keefe <[email-masked]>
Date: Fri, 10 May 2002 14:52:08 -0400

Hey!

Scott kinda looks like Clippy (without the glasses) and it sounds like
Scott gets paid as well as Clippy!

However, Scott has more personality than Clippy can ever dream of:=>

Helen

-- 
Helen Keefe
LON-CAPA/ ITR Project Manager
Laboratory for Instructional Technology in Education
111 North Kedzie Labs
East Lansing, MI 48824

E-mail: [email-masked]
Web:   http://www.lite.msu.edu/
Phone: 517-432-9867
Fax:   517-432-5653

---

From: Scott Harrison <[email-masked]>
Date: Fri, 10 May 2002 14:51:49 -0400

What has happened?  Now I am working for Bill Gates?!

---

From: Helen Keefe <[email-masked]>
Date: Fri, 10 May 2002 15:19:45 -0400

Hey Scott,
If you are working for Gates, you better ask for a big raise!

Helen