Mail Archives: djgpp/2002/12/22/10:30:11
> > (as an additional note: the whole "documentation"
> > structure could be improved.)
>
> Where? Web or info documentation? How? Could you elaborate please?
web and "info";
quick explanation:
FAQ: too much in one file: web browsers scrollbar is tiny; difficult to move up and down; better:
each section in one file, the ToC (1-25) divided into sections too (1-5,6-8,...), so there are just
~5 headings on the first page + FAQ List text. The sections content has then one file for itself too
(so eg. the complete 1 over 3,3.1,...3.10,5 ToC on one page) and each "expanded" Q&A section (so 3
for example) is -as already written- in one file then too.
At the top of each "page" (so 1 html file (not as in 1 printed page)) is a navigation bar; this just
contains the sections headers next to each other an the sections numbers below them
(Getting Started, Using djgpp,...
1-5 6-8 )
and the current major section (so 1-5, not 3) is highlighted.
The FAQ's content is actually quite good, but the name FAQ doesn't suggest all the content which can
be found in the FAQ, so it should perhaps renamed to sth. like "djgpp Usage reference" (not thought
about that name)?
Readme: too much unrelevant information at the beginning (one has already downloaded and "installed"
!); keep the 4 lines on Getting Started; put that at the beginning after the introductory text "...
is a... environment for developing ...", but make that paragraph short too; also mention that it's a
gcc port and that one has to look into the gcc manual on gnu (which is on delorie.com/gnu too and
not on delorie.com/djgpp but a beginner has no idea...) to find info about all commandline arguments
to djgpps gcc for example (which was my main first only interest when using a commandline compiler)!
Web: th eonly really helpful resource for beginners on delorie.com is the FAQ (but that comes with
zips too): User's Guide: link not working; how-to repository: specialised topics, irrelevanmt for
beginners (mainly...), C library refernce: good! ; djgpp documentation: most is unrelevant for
beginners, project overview shortcomings: too much on 1 html page!; that leaves only the FAQ, as
written, it might be better to rename it. (the web version is too much interdivided!! (each 0.1 on
one page; much too much mouse clicks necessary); GNU manuals: coming from Ms world, one has no idea
what gnu is and what djgpp has got to do with it, the link seems to link to a long list of words, an
index, but one can't be bothered to even start reading;
overall problem: too much information, the docs don't get to the point fast enough; one doesn't know
where to reliably find the information one needs. where to find: FAQ or gcc.gnu.org manuals. If
there are many links, one doesn't know whether they lead them to a point where there is real
reference and when having followed some levels of links and lawys being on new pages, one looses
overview of where really to look or better said, where the best information really is. That's a
problem of the FAQ too. So the whole structure should be clear from the beginning and when one
follows a link, one should know in which part of the doc structure one is, that means, what the
theme of the section is one has landed in.
info: didn't download it; I thought rhide would be sufficient (but which I don't use because of the
quirk that each DOS window on my PC seems to get it's own environment setting copy, so set from one
don't activate in the other, so calling a .bat which sets a path and closes after that has no effect
at all, also rhide seems to always load the last file I worked on automatically and I didn't find
the option to switch this off; I don't like this behaviour!); but from the readme it looks as if one
has to know the info file one wants to read and that one has to learn its keyboard navigation
interface. If it needs pure keyborad navigation and if it doesn't lay out the whole doc structire
clearly before me (that is the content it wants to make readble), I can't use it. I then stick to
gcc -o hello.c and don't go into the specifics of the compiler.
- Raw text -