[Axiom-developer] RE: Documentation of the Wiki

[Page, Bill]

On Thursday, November 24, 2005 11:57 AM Martin Rubey wrote:
> 
> I insist: the problem is *not* that there wouldn't be enough
> documentation. Rather, there is too much to read.
>

In general, I agree with you and I have already said something
similar previously.

> Of course, long text can be good. However, I'm afraid that 
> most pages of the Wiki where long text passages appear are
> not read at all.

Actually, on the wiki we can get specific statistics about
how often a page is read. I think the numbers show quite high
hit rates for pages that are accessible from the front page
and those that are indexed on Google quite independent of their
size. If we want, I think we can even make these hit rates
visible on the pages themselves.

But the reasons and the manner in which web pages are read is
quite different than the way email is read. Probably these days
most people are suffering from much more email overload than
used to be the case, so they become quite selective about what
they "read-to-remember" from their email in basket. On the other
hand when people go to the trouble of surfing to a particular
web page, I expect they (usually) take the time to determine if
it really is of interest to them. So I do not think long web
pages are a problem.

Long emails - even this reply - are a different issue. I expect
that most people except maybe you and Tim have already stopped
reading this. ;)

> 
> Thus: please do not 
> 
> > I will see what I can do to write an executive overview.
> 
> from scratch.

In reply to Tim's suggestion my intention was not to create any
new web pages, but rather to just a posting to this email list
that could be repeated as necessary when someone asks about the
features related to the web sites. That mostly means finding
stuff on the existing web pages and formatting it as an email.

> Rather -- given that you have the time -- rewrite the existing
> pages such that they are more succinct.

:( Of course I do not really have time for that ... making
something short and succinct takes a lot of time, experience
and thought.

> 
> In the case at hand, this would probably be 
> 
> 
> http://wiki.axiom-developer.org/HelpPage
> 
> http://wiki.axiom-developer.org/MathAction
> 
> http://wiki.axiom-developer.org/AboutMathAction
> 
> especially the existence of the latter two is highly dubious. 
> They seem to be quite similar...
>

I'll look at the possibility of merging the last two.
 
> 
> On the HelpPage, we find
> 
>   Click "edit" to change the page's text. You may also be able
> to rename the page, upload a file, or choose other options here.
> 
> but no indication how this can be done. Personally, I prefer 
> to see an example, so maybe a link to a SandBox page would be
> appropriate.

Good idea, but I think/hope there are other people more qualified
than me to write good help information. Remember, this is a wiki.
It is supposed to be a community effort.

> 
> By the way, concerning the upload feature: Some time ago I 
> realized that uploading a file with the same name as an already
> existing file would simply overwrite the old "version". Maybe
> uploaded files should be "local" to their page, if this is
> feasible...
> 

Because of it's underlying simplistic design, that is not
possible on the wiki without major changes. The portal however
is both more complex and more flexible because files are
associated with individual users and there is a "workflow",
i.e. review and approval process, associated with making
documents publicly accessible.

On the wiki I suggest that when uploading a file that is specific
to a page, we try to make sure that the name of the file includes
as a prefix the name of the page.

Regards,
Bill Page.