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/
