Reshaping the "Contributing to Django" documentation
32 views
Skip to first unread message
Julien Phalip
May 20, 2011, 5:31:44 AM5/20/11
to Django developers
Hi there,
I've been working on reshaping the documentation about contributing to
Django, in particular the rather dense historical page [1] and the
excellent recently added how-to guide [2]. This documentation has sort
of grown organically over the years and has become a bit difficult to
read, so I tried to improve things a bit.
I've submitted a patch in the designated ticket: http://code.djangoproject.com/ticket/15796
You can also browse the html output here:
http://dl.dropbox.com/u/3364022/djangodoc/internals/contributing/index.html
The vast majority of the content was preserved. What I've done is:
- broke the content down into logical sections.
- merged information about "the documentation" from [1] and [3].
- merged information about "ticket triage" from [1] and [2].
- made a few edits, clarified a few things here and there, shifted a
few bits around and smoothed out the transitions.
- cross-linked the various sections.
- added descriptions for the recently added "type" and "severity"
attributes.
- added a few suggestions for ways new contributors can help.
I hope that it turns this documentation into a more maintainable and
extensible shape and, as a result, that it will facilitate
contributions from the community.
It is a big change so I thought I'd bring it up here in case you have
ideas and suggestions to improve it further or differently. Any
feedback is welcome.
Thanks a lot!
Julien
[1] http://docs.djangoproject.com/en/dev/internals/contributing/
[2] http://docs.djangoproject.com/en/dev/howto/contribute/
[3] http://docs.djangoproject.com/en/dev/internals/documentation/
I've been working on reshaping the documentation about contributing to
Django, in particular the rather dense historical page [1] and the
excellent recently added how-to guide [2]. This documentation has sort
of grown organically over the years and has become a bit difficult to
read, so I tried to improve things a bit.
I've submitted a patch in the designated ticket: http://code.djangoproject.com/ticket/15796
You can also browse the html output here:
http://dl.dropbox.com/u/3364022/djangodoc/internals/contributing/index.html
The vast majority of the content was preserved. What I've done is:
- broke the content down into logical sections.
- merged information about "the documentation" from [1] and [3].
- merged information about "ticket triage" from [1] and [2].
- made a few edits, clarified a few things here and there, shifted a
few bits around and smoothed out the transitions.
- cross-linked the various sections.
- added descriptions for the recently added "type" and "severity"
attributes.
- added a few suggestions for ways new contributors can help.
I hope that it turns this documentation into a more maintainable and
extensible shape and, as a result, that it will facilitate
contributions from the community.
It is a big change so I thought I'd bring it up here in case you have
ideas and suggestions to improve it further or differently. Any
feedback is welcome.
Thanks a lot!
Julien
[1] http://docs.djangoproject.com/en/dev/internals/contributing/
[2] http://docs.djangoproject.com/en/dev/howto/contribute/
[3] http://docs.djangoproject.com/en/dev/internals/documentation/
Waylan Limberg
May 20, 2011, 11:33:58 AM5/20/11
to django-d...@googlegroups.com
On Fri, May 20, 2011 at 5:31 AM, Julien Phalip <jph...@gmail.com> wrote:
> Hi there,
>
> I've been working on reshaping the documentation about contributing to
> Django, in particular the rather dense historical page [1] and the
> excellent recently added how-to guide [2]. This documentation has sort
> of grown organically over the years and has become a bit difficult to
> read, so I tried to improve things a bit.
>
> I've submitted a patch in the designated ticket: http://code.djangoproject.com/ticket/15796
> Hi there,
>
> I've been working on reshaping the documentation about contributing to
> Django, in particular the rather dense historical page [1] and the
> excellent recently added how-to guide [2]. This documentation has sort
> of grown organically over the years and has become a bit difficult to
> read, so I tried to improve things a bit.
>
> I've submitted a patch in the designated ticket: http://code.djangoproject.com/ticket/15796
Awesome!
One nitpick thought. I expect that people reporting bugs will go to
the "bugs-and-features" page, which is fine. However, as is often the
case, when their ticket is marked "accepted" (or some other triage
stage) they often get confused about what that means (as we all know).
If they are only looking to get their one ticket fixed, I doubt they
will find on there own the explanations of the various stages now
under "triaging-tickets" ("I just want my one ticket fixed. I don't
have time to work on other peoples tickets, Why would I look there?").
Perhaps a link to those explanations should be added to the
"bugs-and-features" section? Just a thought.
--
----
\X/ /-\ `/ |_ /-\ |\|
Waylan Limberg
Jonas H.
May 20, 2011, 12:15:52 PM5/20/11
to django-d...@googlegroups.com
> "[...] try and duplicate it. If you can duplicate it [...]"
I'd stick with "reproduce" here because "duplicate" may be confused with
"duplicate tickets".
Julien Phalip
May 21, 2011, 9:37:43 AM5/21/11
to Django developers
On May 21, 1:33 am, Waylan Limberg <way...@gmail.com> wrote:
> One nitpick thought. I expect that people reporting bugs will go to
> the "bugs-and-features" page, which is fine. However, as is often the
> case, when their ticket is marked "accepted" (or some other triage
> stage) they often get confused about what that means (as we all know).
> If they are only looking to get their one ticket fixed, I doubt they
> will find on there own the explanations of the various stages now
> under "triaging-tickets" ("I just want my one ticket fixed. I don't
> have time to work on other peoples tickets, Why would I look there?").
> Perhaps a link to those explanations should be added to the
> "bugs-and-features" section? Just a thought.
Thanks for the tip! In the latest patch I've added such links at the
> One nitpick thought. I expect that people reporting bugs will go to
> the "bugs-and-features" page, which is fine. However, as is often the
> case, when their ticket is marked "accepted" (or some other triage
> stage) they often get confused about what that means (as we all know).
> If they are only looking to get their one ticket fixed, I doubt they
> will find on there own the explanations of the various stages now
> under "triaging-tickets" ("I just want my one ticket fixed. I don't
> have time to work on other peoples tickets, Why would I look there?").
> Perhaps a link to those explanations should be added to the
> "bugs-and-features" section? Just a thought.
bottom of those two sections:
http://dl.dropbox.com/u/3364022/djangodoc/internals/contributing/bugs-and-features.html#reporting-bugs
http://dl.dropbox.com/u/3364022/djangodoc/internals/contributing/bugs-and-features.html#requesting-features
Julien Phalip
May 21, 2011, 9:38:36 AM5/21/11
to Django developers
Reply all
Reply to author
Forward
0 new messages