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
To: interest@qt-project.org
Cc: Mark Griffith
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@qt-project.org
http://lists.qt-project.org/mailman/listinfo/interest___
Interest mailing list
Interest@qt-project.org
http://lists.qt-project.org/mailman/listinfo/interest
