[Phpmyadmin-devel] suggestion for Documentation after 2.3

[Marc Delisle]

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