Hakki wrote:
> I'm working on the PPro DOC and I just uploaded a working copy to
<snip>
> I'd appreciate your comments.

I had a look at Hakki's powerpro_doc.0.1.doc.

Generally, I disagree with the view that Bruce's docs are so
awful that *anything* different will be better. Even Bruce himself
sometimes seems to be humbly concurring with that view. IMHO that
is inappropriately self-deprecating.
So far, the main value I could find in Hakki's alternatives is this:
they demonstrate that Bruce's docs ain't so bad after all.

I acknowledge that this is only a start, not a finished product,
but if the changes so far are an indication then I am worried.
Almost everywhere that Hakki has made changes, Bruce's original
Help and Doc are clearly better.

I shall mention just a few examples, from the first few pages,
to demonstrate how Hakki's new version introduces major errors
in the factual content and also his re-formatting is often worse.


For example early in the doc he added two sections, one headed
"Syntax rules" and one headed "Captions and caption lists".

The topic in Bruce's .hlp about caption lists is missing from
the .doc, so Hakki is right to add a page to the doc about this.

But if you read the Help topic about caption lists
(or my version of the same in the PPdb|sExpr|captionlist)
you will see that Hakki's new description has so many ommissions
it only covers 25% of what Bruce describes.
Hakki's version describes Part Title as one of the possible items
in a caption list but does not even mention =exename or handles or classes.

An even worse example, Hakki's new "Syntax rules" section not only
omits most of the subject, the small amount of the subject which it
attempts to cover is awfully faulty.
Most of what he wrote about where "quotes" are required is simply wrong.

Oddly, most of this new Syntax section is about using the &(expr) form.
As you can see from Bruce's recent messages, he wishes to de-emphasise
the use of &() but Hakki's new section gives the impression that &() is
an essential part of the syntax, the first thing one should learn to use.

I agree it might be good to add a section about the syntax rules
generally. However if it is so incomplete, and also mostly misleading,
it would be better not to include it at all.
_____________________________________________________________

All these new errors demonstrate how bizarre it is for a new user
who has not yet developed a general overview nor a detailed
understanding of the program to attempt to rewrite Help.
_____________________________________________________________

Similarly with the formatting:
Even though Bruce doesn't claim to be "a designer", he clearly
understands the subject matter better and therefore has formatted
it more intelligently and appropriately - for example the section
called "Power and Flexibility of PowerPro" where Bruce has used
bulletted lists, which Hakki has (inappropriately) split into many
more cells in the table, making the topic more difficult to read
and understand - and also uglier.

That is not just a matter of my personal aesthetic preference;
it would be quite easy, but too time consuming, to describe all of
the various technical reasons why Bruce's version of the "Power and
Flexibility of PowerPro" page is kinder to the reader.
Briefly, although both Bruce and Hakki use a table for this topic,
Bruce's version uses fewer cells and therefore looks more like
two Columns rather than a Table. That suits the subject because
there is no one-to-one correlation between paragraphs in the left
column and those in the right column. By using fewer cells, the
vertical continuity of each column is stronger than left to right.
Also, Bruce kindly resisted applying unpleasant background colors
to his table.

Generally I find the design Hakki has imposed on all tables,
with that dark blue and bright yellow, is ugly and does not
improve the reading experience.
Why use that particular 0 0 128 blue? and that yellow?
Word .doc files (and also .rtf files) now allow the character
highlighting (aka shading) to use any of the 64 million rgb colors.
Admittedly MS Word's toolbar icon's dropdown thing hasn't caught up
with improvements in the Word .doc features and still only offers
a few standard colors.
That is easy to work around, using a home made macro for instance
or a new Character Style. A less saturated yellow would be less
cruel to the eye.
Using a 192 192 192 background for samples of code is an even
worse decision.
_____________________________________________________________

In an earlier message I wrote:
> I'm happy to leave the organising and coordinating decisions
> to you Hakki because you seem to know what you are doing
> and you have a clear vision of what you want to create.
> So I'm willing to fit in flexibly however you wish. :-)

Having checked out Hakki's new version of the doc,
I must adjust that view. It would be wiser for me not
to attempt teamwork in this particular situation
as I cannot feel optimistic that the new product
will be better than the existing documentation.

Alan Martin




------------------------ Yahoo! Groups Sponsor --------------------~--> 
Yahoo! Domains - Claim yours for only $14.70
http://us.click.yahoo.com/Z1wmxD/DREIAA/yQLSAA/JV_rlB/TM
--------------------------------------------------------------------~-> 

 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
     http://groups.yahoo.com/group/power-pro/

<*> To unsubscribe from this group, send an email to:
     [EMAIL PROTECTED]

<*> Your use of Yahoo! Groups is subject to:
     http://docs.yahoo.com/info/terms/
 

Reply via email to