[Phpmyadmin-devel] suggestion for Documentation after 2.3

[Robin Johnson]

On Wed, 24 Jul 2002, [utf-7] Beck, Mike wrote:
> what i think should still be improved is the way to get to the
> documentation... at the moment we basically assume (hope/pray whatever) that
> anybody has read the document fully and still remembers it when he uses PMA.
While that may be true of most people that install phpMyAdmin themselves,
it is not true if they are installing it for an ISP type setting, where
there are other users besides the one that installed it.

> then we would 'just' have to go through the docu and enter lots of anchors
> so we can call this function at all places throughout pma to show the user
> an easy way towards the docu.
There are quite a few anchors already, and it would not be too hard to add
more.

> idealy a ? icon should be beside every user input field. now this would
> require some more docu +AF8-and+AF8- i really think by then we should split up the
> docu into smaller parts, so that we don't need to send the whole docu file
> every time, so it would be something like:
> call+AF8-docu(+ACQ-topic,+ACQ-anchor).
I like the idea of splitting it up, as that makes it easier to manage as
well.

> i expect it will take some time until this is fully realized, but i'd
> suggest i'd do a function for it after 2.3.0 and start splitting the docu
> and then everybody could just try to keep in mind to add some functioncall
> if he stumbles across some place in the source that needs explanation, so it
> will get better after time.
in a library:
<?php
function PMA_HelpLink($ref)
{
    globals $cfg;
    if ($cfg['Display_HelpLinks']) {
        $str = '<a href="Documentation.php#'.$ref.'"
onclick="..."><sup>?</sup></a>';
    } else {
        $str = '';
    }

    return $str;
} // end of the "PMA_HelpLink()" function
?>

I have the configuration variable there on purpose, as in some cases I run
with limited screen space, and I would want to turn off the help links, as
I know what I am doing.

> so:
>  1) do you agree to try to go in this direction
Yes.

>  2) wasn't there some thought on having the docu in a different format?
> (sgml, xml or whatever)
Yes. No format was decided on. I'd be in favour of having the master
document in SGML/XML, split up into little sections.
Possible directory structure:

Documentation/
 xml/
 html/
 text/
 (etc for each format)

under each format:
 english-iso-8859-1/
 japanese-euc/
 (etc, so that we can have translated Documentation)

Under each language (files):
Index
Requirements
Introduction
Installation
Configuration
FAQ
Developers
Credits

I think XML masters would be ideal, as with XSLT stylesheets on our
master side when we are rolling a package, we can build all the
documentation easily. There would also be room to produce more formats
easily from the XML, such as Info, LaTeX and PDF. I don't know if one can
do this from SGML or not.

>  3) i expect nobody ever really hoped we could get the whole docu
> translated, or?
It will be a slow process for documentation, but it can be done in the
long term.

-- 
Robin Hugh Johnson
E-Mail     : robbat2 at orbis-terrarum.net
Home Page  : http://www.orbis-terrarum.net/?l=people.robbat2
ICQ#       : 30269588 or 41961639