[prev in list] [next in list] [prev in thread] [next in thread] 

List:       quanta
Subject:    Re: [Quanta] Quanta Documentation: English
From:       Eric Laffoon <sequitur () kde ! org>
Date:       2007-02-02 21:28:51
Message-ID: 200702021328.51608.sequitur () kde ! org
[Download RAW message or body]

On Friday 02 February 2007 10:17 am, Paul Lemmons wrote:
> We developers should never write end user documentation. Even when the
> audience is other developers. We all suffer from the "It is intuitively
> obvious by simple observation" syndrome.&nbsp; There is a completely
> different skill set used in writing documentation. Documentation should
> be written by those than have the skill to do it. Our role in
> documentation is to simply complain about it :)<br>

First of all I find it difficult to follow someone I don't know posting on the 
list using HTML claiming to be a developer. I'm just not buying this up 
front, or I didn't see your commits. Having said that...

The primary reasons developers should not write documentation are as follows.
1) Good documentation is very time consuming. That is a great deal of time 
taken away from development. Good development is time consuming and we are 
already short on resources there.

2) A developer writing documentation can go by what they remember and how 
things were intended to work. Someone else has to go through a process of 
exploration based upon thumbnail information from developers. In this process 
there is also exploration and enhanced confirmation of operation as well as 
feedback to the developer. This can uncover critical bugs and UI issues.

3) While there are different skill sets for developing and writing 
documentation it is less an issue than the excellence you can bring to the 
table with a single focus and applicable perspective. Developers may consider 
some less than intuitive aspects to be fundamental givens. We can also feel 
very inadequate trying to reframe our point of reference.

The final reason is that Quanta it's self is the best free tool to write 
documentation. There are a great many users who could easily take this on. 
You're getting free software that we are actually spending money to make and 
time to manage and service. Why not feel good about bringing your skills to 
the party? If you don't think you know the application good enough then 
consider after you write the docs interacting with the developers you will 
then. What a deal! ;-)
-- 
Eric Laffoon - Quanta+ Team Leader 
http://quanta.kdewebdev.org
_______________________________________________
Quanta mailing list
Quanta@mail.kde.org
https://mail.kde.org/mailman/listinfo/quanta
[prev in list] [next in list] [prev in thread] [next in thread]