[Interest] my comparison with company reports

[Jason H]

Mark, I know you mean well, but Qt has the best documentation in the industry.
I think your complaints come from your own short comings as a developer, as Qt docs are written with developers for developers. So the question is audience. I think it's good that you're versatile, but you're clearly not yet in the audience for which the documentation is intended. What you propose is actually impossible, because the intersection of all possible audiences is too large. The resulting documentation for n00bs would be too verbose for actual developers.

So from a company report perspective, how about you write a resort on how the documentation must be changed to conform to your standards, including labor and cost estimates, then compare it to the labor and cost involved to align you to the documentation's audience. I think I know how that evaluation will turn out.

I hope that helps put things in perspective. 


But if you have specific criticisms or ideas on how to improve it, we would hear them.





________________________________
 From: Mark Griffith <markgriffith at yahoo.com>
To: interest at qt-project.org 
Cc: Mark Griffith <markgriffith at yahoo.com> 
Sent: Thursday, April 12, 2012 8:45 AM
Subject: [Interest] my comparison with company reports
 

.

Dear R. Reucher, 

thanks for your response about company reports - actually that's not quite true. I'm not an economist telling you they are clear. I'm an economist telling you we expect them to be clear, and even though most of them are unclear there is general agreement they should and could rise to a higher level of comprehensibility. I never said they were clear already. But people are at least trying, and not saying they should be for initiates only. 

There are two battles here. (1) Everyone agreeing that clarity for intelligent general readers can be achieved and that this is a shared goal, and (2) actually achieving this indisputably difficult goal. 

What I should have said - my apologies for being unclear there - is that goal (1) has been achieved with company reports by and large. No-one in business (at least out loud)
 defends the proposition that company reports should only ever be read by people with economics or accountancy training - there is at least lip service paid to the idea that small shareholders with no training deserve access to the information too. (2) is harder. I have worked on company reports myself but - as with my other post about user manuals - never had the editorial freedom to make them as clear as they could and should be. 

In contrast, with software documentation goal (1) has not been achieved. You, like many others in this field, feel it is a basic mistake to assume software documentation can ever be made clear to complete beginners. This is why you naturally assumed I was saying company reports were clear, and only saying so because I've studied economics. No. I said we all _expect_ company reports to be clear (and rightly so). The first battle has been won in terms of communicating ideas in economics and finance, and the second battle
 is now in progress. 

Mark G. 

 
_______________________________________________
Interest mailing list
Interest at qt-project.org
http://lists.qt-project.org/mailman/listinfo/interest
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20120412/be4e0e50/attachment.html>