[Twisted-Python] User notes for documentation.
illumen at yahoo.com
Sat Jul 5 22:42:51 EDT 2003
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
> 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,
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.
More information about the Twisted-Python