24 Jul
2002
24 Jul
'02
7:22 a.m.
hi all,
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.
now my suggestion would be to have a small function
call_docu($anchor)
which, depending on wether javascript can be used, will write the javascript
code to open the docu at the specified anchor, or a simple <a href> together
with some nice little ? symbol.
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.
idealy a ? icon should be beside every user input field. now this would
require some more docu _and_ 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_docu($topic,$anchor).
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.
so:
1) do you agree to try to go in this direction
2) wasn't there some thought on having the docu in a different format?
(sgml, xml or whatever)
3) i expect nobody ever really hoped we could get the whole docu
translated, or?
--
Mike Beck
mike.beck(a)users.sourceforge.net
24 Jul
24 Jul
7:52 a.m.
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(a)orbis-terrarum.net
Home Page : http://www.orbis-terrarum.net/?l=people.robbat2
ICQ# : 30269588 or 41961639
8:07 a.m.
Beck wrote:
hi all,
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.
No, I assume that they did not read it :)
now my suggestion would be to have a small function
call_docu($anchor)
which, depending on wether javascript can be used, will write the javascript
code to open the docu at the specified anchor, or a simple <a href> together
with some nice little ? symbol.
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.
I agree.
idealy a ? icon should be beside every user input field.
Maybe not _every_ input fields, or the interface will be really full of
question marks.
now this would
require some more docu _and_ 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_docu($topic,$anchor).
If feasible, I would prefer to keep only one file, because:
1. easier to print
2. easier to search into
But I realize that projects like mysql.com have it all: one file per
subject, one file per chapter, one big file, or PDF.
By the way, I thought that the browser cache would keep
Documentation.html in memory, but I just made a test and it is sent
again. Anybody knows why?
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.
so:
1) do you agree to try to go in this direction
2) wasn't there some thought on having the docu in a different format?
(sgml, xml or whatever)
I am not familiar with those, can't comment.
3) i expect nobody ever really hoped we could get the
whole docu
translated, or?
I think at least the Install section should be translated (but wait, the
English version needs reworking)
--
Marc Delisle
8:18 a.m.
On Wed, 24 Jul 2002, Marc Delisle wrote:
Hmm, actually thinking about this more,
It would be nice to have a few levels of help for displaying the question
marks.
(Using defined constants)
HELP_NONE
HELP_COMMON
HELP_RARE
HELP_ALL (really HELP_COMMON | HELP_RARE)
The 'rare' ones would be things that are not commonly used, as opposed to
the common ones.
Ok.
--
Robin Hugh Johnson
E-Mail : robbat2(a)orbis-terrarum.net
Home Page : http://www.orbis-terrarum.net/?l=people.robbat2
ICQ# : 30269588 or 41961639
idealy a ?
icon should be beside every user input field.
Maybe not +AF8-every+AF8- input
fields, or the interface will be really full of
question marks. If feasible, I would prefer to keep only one file,
because:
1. easier to print
2. easier to search into
But I realize that projects like mysql.com have it all: one file per
subject, one file per chapter, one big file, or PDF.
Actually, if we split it up
for the master, we can generate all of the
other formats you want.
html-split
html-complete
etc.
By the way, I thought that the browser cache would
keep
Documentation.html in memory, but I just made a test and it is sent
again. Anybody knows why?
Nope.
3) i expect
nobody ever really hoped we could get the whole docu
translated, or?
I think at least the Install section should be translated (but
wait, the
English version needs reworking) 
25 Jul
25 Jul
7:33 a.m.
New subject: [Phpmyadmin-devel] Re: suggestion for Documentation after 2.3
Beck, Mike wrote:
hi all,
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.
now my suggestion would be to have a small function
call+AF8-docu(+ACQ-anchor)
which, depending on wether javascript can be used, will write the
javascript
code to open the docu at the specified anchor, or a simple +ADw-a
href+AD4- together
with some nice little ? symbol.
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.
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).
My idea was to introduce something like context help in phpMyAdmin.
I'd also add those ? icons to the interface, but instead of jumping to an
anchor in the documentation I'd prefer to display a short (maybe even
localized) text in a JS window that tells the user more a bout a specific interface
element.
I'd also offer this context help for popular error messages i.e. if the
MySQL server refuses the username / password.
2) wasn't there some thought on having the docu
in a different format?
(sgml, xml or whatever)
XML would allow us to translate and modify the documentation more easily.
3) i expect nobody ever really hoped we could get the
whole docu
translated, or?
During the Easter holidays I had a little too much time... So... I have a
German docu for 2.2.6-dev that is at about 50%... ;-)
I don't think we need a translated documentation in the distribution, but it
would be something nice for phpMyAdmin.net, wouldn't it?
Have a clean RC4,
Alexander
--
GMX - Die Kommunikationsplattform im Internet.
http://www.gmx.net
8:14 a.m.
New subject: [Phpmyadmin-devel] Re: suggestion for Documentation after 2.3
Alexander Turek wrote:
Yep.
Beck, Mike wrote:
>hi all,
>
>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.
My idea was to introduce something like context help in phpMyAdmin.
I'd also add those ? icons to the interface, but instead of jumping to an
anchor in the documentation I'd prefer to display a short (maybe even
localized) text in a JS window that tells the user more a bout a specific interface
element.
I'd also offer this context help for popular error messages i.e. if the
MySQL server refuses the username / password.
I definitely support this idea of context help, using the /lang files.
I don't think that we need to change the format of those files, for
context help.
2) wasn't there some thought on having the
docu in a different format?
(sgml, xml or whatever)
XML would allow us to translate and modify the documentation more easily.
3) i expect nobody ever really hoped we could get
the whole docu
translated, or?
During the Easter holidays I had a little too much time... So... I have a
German docu for 2.2.6-dev that is at about 50%... ;-)
I don't think we need a translated documentation in the distribution, but it
would be something nice for phpMyAdmin.net, wouldn't it?
Have a clean RC4,
Sure :)
Alexander
still on the beach?
--
Marc Delisle
27 Jul
27 Jul
8:28 a.m.
New subject: [Phpmyadmin-devel] Re: suggestion for Documentation after 2.3
Marc Delisle wrote:
Alexander Turek wrote:
I'd like to seperate the help texts from the normal messages maybe by
changing the variable prefix: we'd use $helpSomething instead of $strSomething for
instance.
My idea was to introduce something like context help in phpMyAdmin.
I'd also add those ? icons to the interface, but instead of jumping to
an anchor in the documentation I'd prefer to display a short (maybe
even localized) text in a JS window that tells the user more a bout a
specific interface element.
I'd also offer this context help for popular error messages i.e. if the
MySQL server refuses the username / password.
I definitely support this idea of context help, using the /lang files.
I don't think that we need to change the format of those files, for
context help. still on the beach?
Yes, I'll stay in Greece until August 3rd :-)
Alexander
--
GMX - Die Kommunikationsplattform im Internet.
http://www.gmx.net
8078
days inactive
8081
days old
6 comments
4 participants
participants (4)
-
Alexander Turek -
Beck, Mike -
Marc Delisle -
Robin Johnson