In version 12 it was one page with a short abstract only. In
version 13 and latest sources there are also credits with authors and
editors. This division makes additional expandable "book" in TOC with
all bookmarks leading to the same page. I do not know if it confuses
users, but for me such division is useless and make manual look more
like hardcopy books, where you do not need to look at these pages as
long as you don't interested in that kind of information. But that's
not true for xCHM version where this attention can decrease usability
because frequently accessed information is located among similar
graphical markup.
I'm writing this with a great respect to all manual developers,
editors, authors and contributors, because I think PHP manual is a
major part of PHP success on windows platform. That's why I'm asking
about what will be the best way to include information about people,
who contributed to PHP docs in xCHM version. I have some proposals:
1. Leave as is
Default way some may easily agree with because of simplicity in
implementation (which should not be the goal, right?). That way
we will have structure like
Preface
Authors and Contributors
Authors and Editors
User Note Maintainers
as the third item of the manual TOC. Decreases usability by
adding additional burden for users reading additional book title
and perhaps contents to locate needed manual part.
GH> I had a hard time to undestand the point. These TOC items are expandable GH> from the Preface hierarchy, and by default they are not expanded. Or am GH> I mistaken?
You are right. They are not expanded by default, but displayed as a
"book", so one still need to read the title to see what it is only
Preface. To get to function reference you will need to review 7 upper
"books" titles. After that one can become interested what can be in
preface so authors made it expandable. One clicks the "book" and sees
another "book". Inside second book there are two bookmarks, but this
is still the same Preface page. So many excess operations just because
of curiosity which at the same time don't reveal any new interesting
information makes one feel uncomfortable, slightly disappointed. Maybe
one was looking for PHP Tutorial, which is actually in Getting Started
or Install Instructions and thought it can be in Preface part.
Since traditional textbooks use a similar formatting, I don't have a problem with this solution. Those who would like to conquer the preface will finally found our names :) This is not bad :))
Goba