471,852 Members | 1,020 Online
Bytes | Software Development & Data Engineering Community
Post +

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 471,852 software developers and data experts.

How to change the docs - a case study

There has been a lot of discussion here recently about making changes to
the docs, and what new system should be in place, etc., wiki, etc. I
occasionally chime in with a note that it's pretty easy to submit a doc
patch through SourceForge and they are often accepted quickly. The point
being that there is a system in place that in my experience works pretty
well.

Here is an example. This morning I noticed a minor discrepancy in the
docs for the 'rot13' encoding. I posted a bug to SourceForge at 10:05
GMT. At 10:59 someone commented that maybe the code was broken rather
than the docs. At 11:18 another poster responded that the code should
stay the same. At 11:25, less than two hours after my original report, a
fixed was checked in.

The complete exchange is here:
https://sourceforge.net/tracker/?fun...&group_id=5470

Kent
Apr 6 '06 #1
3 1113
Kent Johnson wrote:
Here is an example. This morning I noticed a minor discrepancy in the
docs for the 'rot13' encoding. I posted a bug to SourceForge at 10:05
GMT. At 10:59 someone commented that maybe the code was broken rather
than the docs. At 11:18 another poster responded that the code should
stay the same. At 11:25, less than two hours after my original report, a
fixed was checked in.
how many manhours did this take, in total ? did you clock your own efforts ?
The complete exchange is here:
https://sourceforge.net/tracker/?fun...&group_id=5470
the 2.4.3 doc is still broken:

http://docs.python.org/lib/standard-encodings.html

(and if I hadn't kicked people around a couple of months ago, even the development
documentation, which still hasn't been updated, btw, would remain broken for another
4-6 months.)
The point being that there is a system in place that in my experience works pretty
well.


so you're saying that we cannot do better, and that people who try should do some-
thing else with their time ?

</F>

Apr 6 '06 #2
Fredrik Lundh wrote:
Kent Johnson wrote:
Here is an example. This morning I noticed a minor discrepancy in the
docs for the 'rot13' encoding. I posted a bug to SourceForge at 10:05
GMT. At 10:59 someone commented that maybe the code was broken rather
than the docs. At 11:18 another poster responded that the code should
stay the same. At 11:25, less than two hours after my original report, a
fixed was checked in.
how many manhours did this take, in total ? did you clock your own efforts ?


It took a few minutes of my time. Maybe a minute to verify that there
was no similar bug report, a few minutes to write up my findings and
submit them. I don't know how much time the other posters spent but the
total clock time from OP to fix was 1 hour 20 minutes so that gives you
an upper bound.
The complete exchange is here:
https://sourceforge.net/tracker/?fun...&group_id=5470
the 2.4.3 doc is still broken:

http://docs.python.org/lib/standard-encodings.html

(and if I hadn't kicked people around a couple of months ago, even the development
documentation, which still hasn't been updated, btw, would remain broken for another
4-6 months.)


My understanding is that there is a build step required. So the change
isn't public yet but I expect it will be.
The point being that there is a system in place that in my experience works pretty
well.


so you're saying that we cannot do better, and that people who try should do some-
thing else with their time ?


No, I didn't say that at all. You are welcome to spend your time as you
like. I'm saying that IMO the current system works pretty well and
suggesting that some people may find posting patches to SourceForge to
be an easy and effective way to change the docs.

Kent
Apr 6 '06 #3
Kent Johnson wrote:
Here is an example. This morning I noticed a minor discrepancy in the
docs for the 'rot13' encoding. I posted a bug to SourceForge at 10:05
GMT. At 10:59 someone commented that maybe the code was broken rather
than the docs. At 11:18 another poster responded that the code should
stay the same. At 11:25, less than two hours after my original report, a
fixed was checked in.
how many manhours did this take, in total ? did you clock your own efforts ?


It took a few minutes of my time. Maybe a minute to verify that there
was no similar bug report, a few minutes to write up my findings and
submit them. I don't know how much time the other posters spent but the
total clock time from OP to fix was 1 hour 20 minutes so that gives you
an upper bound.


now that the developer documentation has been updated, have you verified
that the fix is correct ? if you have, how long did it take (in clock time) be-
fore you got around to do that ?
the 2.4.3 doc is still broken:

http://docs.python.org/lib/standard-encodings.html


for the record, it's still broken. and there's no sign that there's a known
bug on that page.

I've written a little more about this here:

http://pytut.infogami.com/blog/43fm

</F>

Apr 8 '06 #4

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

1 post views Thread by Jamie | last post: by
4 posts views Thread by Richard Cornford | last post: by
3 posts views Thread by CPA Study Group | last post: by
3 posts views Thread by roger beniot | last post: by
10 posts views Thread by Patty O'Dors | last post: by
10 posts views Thread by =?Utf-8?B?U3RlZmFuIEJhcmxvdw==?= | last post: by
39 posts views Thread by Alan Isaac | last post: by
reply views Thread by YellowAndGreen | last post: by
aboka
reply views Thread by aboka | last post: by

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.