ZTree.com  | ZEN  | About...  

 Index   Back

[Docs] ZTW.HLP 1.1   [Docs]

By: John Gruener     Orlando, Florida  
Date: Feb 11,2007 at 09:12
In Response to: [Docs] ZTW.HLP 1.1 (Steve Rawling)


> I'm sorry if you felt obliged to read my post only to discover it was
> "simply" a "better expressed" version of what already
> existed, albeit with 4 errors :-), and so was not of sufficient importance
> to stop the press. Still , as David has pointed out, there is an error in
> the original.

I don't think there was an error, but it would have been much more helpful if you had pointed out the error you were correcting in a comment, rather than simply submitting the entire section reworded and rearranged with no explanation (other than "can IMHO be better expressed as follows").

I could have simply let Kim decide whether to incorporate your submission, but since it was a section I had written I wanted to see what you were suggesting. I then noticed the several errors, so thought I'd better point them out in case he does incorporate it. I didn't even notice that you changed the description of where the highlight bar starts, because you moved it and it was not directly comparable. In fact your new description is yet another error in your modification, as I will explain in my reply to David.

> I'm glad though that you think it is a better expressed version of what
> existed. I humbly point out that I probably could not have written it
> without "standing" on your version, but not being the original
> author sometimes allows one to see more easily where clarity can be
> improved.

There is no doubt that there are literally hundreds of places in the file where clarity can be improved, especially if we understand that each person who modifies it would have a different opinion of exactly how to clarify it. In fact there are some paragraphs and sections that I've not yet touched that I'd like to improve when I have the time.

> I write meany technical reports and sometimes struggle to express some
> issues in a way that combines veracity with readability but yet stay clear
> of spin. I'm sure you have had the same problem.
>
> I often return to a "completed" report after a break of a day or
> week and on rereading am gobsmacked at the convoluted way the issue has
> been presented and so often do major rewrites of "completed"
> reports, prior to submission. Of course one must have the luxury of time
> to be allowed such an indulgence.

I'm afraid the luxury of time is exactly the problem for me right now. I don't at all mind fixing problems, but spending time on "better expression" when I have clients waiting for serious work to be done can get frustrating. So I apologize for my rather hurried and critical reply.

> Less frequently, I have "presented" a first draft to peers and
> they have cut through crap with seeming efffortlessness that I have
> struggled to present, even though they do not have their finger on the
> pulse of the issue. I must say though that I cringe when someone suggests
> a better way of saying something:-)

So why do you cringe? In my case it's not because someone has found a better way of saying things, but because of the time it takes to figure out what was changed and improved.

> The important thing is though that the late revisions often lift the
> report above the wall of incomprehensible technical gobbligook and allows
> it to effectivly convey the desired message.
>
> Sometimes though the revision effect much smaller improvements:-)

The bottom line here Steve is that there is no one way to write technical documentation. Give 1000 people one paragraph to write, and it will result in 1000 variations. Apply that concept to a document as large as ZTW.HLP, and you can see the problem. I do not claim that my way is any better than yours or anyone else's, but I've tried to maintain a certain flow and consistency in the sections I've written or modified.

- John

1,070 views      
Thread locked
 

Messages in this Thread

 
96,637 Postings in 12,231 Threads, 350 registered users, 62 users online (0 registered, 62 guests)
Index | Admin contact |   Forum Time: Mar 28, 2024 - 5:38 pm UTC  |  Hits:62,374,552  (26,949 Today )
RSS Feed