[Interest] thanks for extra reading suggestions - sorry to insult technical writers

[Mark Griffith]

.

Dear David Ching, 
Dear Sivan Greenberg, 
Dear Mark Summerfield, 

thank you all for responding to my bad-tempered post about QT documentation with such positive & helpful ideas. 

Thanks, David - I shall certainly check this!
<< See my blog post:

http://dcsoft.wordpress.com/2010/01/30/qt-book-download-c-gui-programming-wi

th-qt-4-second-edition-by-jasmin-blanchette-and-mark-summerfield-prentice-ha

ll/ or http://bit.ly/HCsmuh >> 



Thanks, Sivan - this looks extremely useful as one of the shortcuts I so badly need!
<< And today you can actually use QML (a dialect of JavaScript) to get up and running in no time. http://qt-project.org/wiki/Qt_Quick_Tutorial >>

Dear Mark - I didn't mean to insult anyone. I actually worked a year as a technical writer myself for a VoIP start-up about 7 years ago and got one or two insights there. The manuals were supposed to be for end-users, but my text was repeatedly changed for being too clear. They were worried their venture-capital funders would think the manuals wouldn't read enough like industry-standard manuals without the jargon. I suggested managers repeat the tests I'd done of my versions on the most computer-naive users I could find, a couple of the sales girls (who much preferred my user instructions to the final versions) but managers wanted all the jargon terms I had taken out put back in. When I defined technical terms, they wanted the definitions taken out too. 

This company collapsed, as I'd expected, but I can imagine similar pressures on technical writers exist in more successful firms. 

I understand computers are complex and software is a wonderful thing, but I wonder who is really qualified to say what is the most sophisticated, elaborate area of knowledge today? Without wishing to pull rank, do you really know so much about finance, accountancy and economics as to be sure that this is a radically simpler subject than software documentation? I think there are lots of complex areas of knowledge - for example I cannot imagine that electronics - teaching circuit designers how to keep unwanted impedance under control for example - is an order of magnitude simpler than software writing. Philosophy is notoriously hard to read and as a philosophy graduate I have no hesitation in saying this is because most philosophers write badly, are working their ideas out as they write them down, and would almost to a man benefit hugely from having a commercial writer edit and rewrite their text for them. You see, I'm quite sure that the managers who put
 the buzzwords back into my user manuals would agree with you - if you asked them - that (they think) their experience "showed them" that user manuals need to be written by people experienced in programming, and I'm sure they say this every time. Doesn't mean they're right in their beliefs though. 

In any case, I'm very grateful for your thoughtful & patient response to my long post. I think on balance (since I'm now a book publisher) I shall have get some writers together and produce a book of the kind I'd like to see ....justify my accusations with a concrete response - to really show what I mean. Of course, I don't think it's possible to teach _anyone_ absolutely _anything_ in text, but I think if the reader is genuinely bright at a couple of other things, they genuinely want to learn, and _still_ finds the introductory texts hard-going, it's probably mainly a failure on the writing side. 

If I ever get enough money to put it where my mouth is and produce that book, I'll let you all know.... and perhaps I'll be proved wrong! Until then, thank you all for your tips about QT and QML and your reasoned, sympathetic responses.

Mark G. 

.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20120412/bed94cdf/attachment.html>