[Phpmyadmin-devel] suggestion for Documentation after 2.3
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@users.sourceforge.net
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@orbis-terrarum.net Home Page : http://www.orbis-terrarum.net/?l=people.robbat2 ICQ# : 30269588 or 41961639
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
On Wed, 24 Jul 2002, Marc Delisle wrote:
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. 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.
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) Ok.
-- Robin Hugh Johnson E-Mail : robbat2@orbis-terrarum.net Home Page : http://www.orbis-terrarum.net/?l=people.robbat2 ICQ# : 30269588 or 41961639
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
Alexander Turek wrote:
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?
Yep.
Have a clean RC4,
Sure :)
Alexander
still on the beach? -- Marc Delisle
Marc Delisle wrote:
Alexander Turek wrote:
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.
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.
still on the beach?
Yes, I'll stay in Greece until August 3rd :-) Alexander -- GMX - Die Kommunikationsplattform im Internet. http://www.gmx.net
participants (4)
-
Alexander Turek -
Beck, Mike -
Marc Delisle -
Robin Johnson