[Twisted-Python] User notes for documentation.

[Rene Dudfield]

Greetings again,


I just spent over an hour or so thinking about this.  Directly below 
this is my possibly useful contribution/suggestion, further below are 
some words strung together.

Add a bug report link/form at the bottom of each section of 
documentation.  This can include feedback on the docs, and bug reports.  
Often times when people are looking at docs, it is because they have a 
problem they want a fix for.  So it makes sense to ask for bug reports 
in the docs.  Like the feed back suggestion of Glyphs, automatically 
include a way to track down which document the report was made from.







Glyph Lefkowitz wrote:

>
> On Friday, July 4, 2003, at 10:58 AM, Rene Dudfield wrote:
>
>> A user notes system has these advantages:
>
>
> These are disadvantages.
>
>>  - not having to bother people to post notes
>
>
> This means that the development team remains unaware of bugs, as the 
> user community just works around them rather than helping to fix them.

The development team can get a list of changes to the pages as they 
happen.  Which will mean they are aware of the problem.

Often times a problem can be documentation oriented.  In that people 
don't know how to use a system.  By adding documentation the user 
community can help fix the problem.

You will always find that some people are prepared to help fix bugs in 
libraries.  Others just want to get on with what they were doing.  Maybe 
you don't want those people using your code?  Which is fine I guess :)

If there are work arounds listed as a user note, then there are two 
things which can happen because of it.  The developers, and users can 
ignore the problem, or the frame work can be fixed to make the work 
around unnessesary.  Allowing people to see if a work around is 
neccesary is probably more benificial.  If you're suggesting that users 
would rather have something working than have to work around bugs, then 
sometimes you would be correct.  No one likes to run into bugs which 
lots of people have encountered.



>
>>  - being easier for people to add a note about something as they are 
>> reading
>
>
> This ease of posting comments and lack of editorial review means that 
> half of the comments will be badly written and the other half will 
> simply be wrong. 

Editorial review remains.  Every now and then(possibly as soon as the 
note is posted) editors can go through the notes to fix up problems.  Or 
as you suggest, having the notes not appear on the page at all, but 
having them sent to a group of editors would be good.

Also other users can post notes about wrong comments which remain.

>
>
> I am strongly opposed to having user-comments on the documentation 
> because it encourages half-assed fixes to problems, both documentation 
> and otherwise.

How does it do this?

I can see how it encourages people to share their experiences about the 
part being documented.  People see how others have noted something 
down.  People feel like they are expected to note down any problems, 
insights, etc.

Often times when people are reading the documentation they are looking 
to solve a problem they have had.  There are other reasons, but that is 
a big one.  So perhaps a bug report form/link at the bottom of the page 
would be good?


>
> However, a snippet at the bottom of each page that said "Is this 
> documentation frustratingly incomplete or incorrect?  Please send 
> feedback to twisted-python at twistedmatrix.com" followed by a suitably 
> munged mailto: hyperlink that will put some information about which 
> page is being referred to in the topic of the message.

Good idea.  That would be quite easy to implement as well.  A bug report 
link/form could be good too.

>
> Also if someone wants to take over as the documentation editor, I will 
> gladly cede decisions like this one to them.  The biggest reason that 
> we don't have very good documentation is that nobody makes it their 
> primary responsibility.
>
Some of the documentation is quite good.  The perspective broker parts 
have been improved lots since I last read them 6-12 months ago.  There's 
also beginning to be some articles written using twisted from sources 
outside the twisted hive mind, which is good.

Another good addition to the docs would be a listing of significant api 
changes.  If it's not in there allready somewhere.  eg differences 
between 1.02 and 1.03, 1.03- 1.04, 1.05-1.06, etc.