Documenting new features: built-in obsolescence of the "versionadded" tag.
richardbarran
The Django documentation places a strong emphasis on highlighting new/
changed features with lines such as:
"New in Django 1.0: Please, see the release notes"
Such comments are a useful mental reminder when scanning through the
docs, they do however have one downside: built-in obsolescence. With
the passage of time (and versions), they will end up referring to long-
forgotten Django releases, and become just cruft.
My question: how long should these "versionadded" tags remain in the
documentation? My $0.02: seeing as only 1.1 and 1.2 are officially
supported, and that *in theory* everyone should already be working
with those - reminders for earlier versions e.g. 1.0 have become
cruft.
Any thoughts?
Tobias McNulty
--
You received this message because you are subscribed to the Google Groups "Django developers" group.
To post to this group, send email to django-d...@googlegroups.com.
To unsubscribe from this group, send email to django-develop...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
--
Tobias McNulty
Caktus Consulting Group, LLC
P.O. Box 1454
Carrboro, NC 27510
USA: +1 (919) 951-0052
http://www.caktusgroup.com
Jeremy Dunck
> I agree. It's a little odd seeings things flagged "New" that have been
> around since 1.0. I also like your proposal of removing the notes for
> unsupported versions.
> Tobias
I think maybe the rendering can just be altered to ignore tags with
the old values?
Gregor Müllegger
documentation but could stop the output in the HTML generation.
2010/7/23 Jeremy Dunck <jdu...@gmail.com>:
Jacob Kaplan-Moss
> I think maybe the rendering can just be altered to ignore tags with
> the old values?
Actually, I think I'd rather just remove them -- plenty of people
(including me) read the docs in plain text, and the "versionadded" is
just cruft.
I'd suggest we strip out any versionadded/changed directives that
refer to versions we no longer support.
Jacob
Justin Lilly
versionadded bits need to be reworked into the body of text. While I
can't remember any specific examples, I remember reading docs a few
times and coming across versionadded statements that were at the
bottom of their section rather than where they would have naturally
flowed in the text.
Russell Keith-Magee
> While I know it comes with extra work, I think the contents of the
> versionadded bits need to be reworked into the body of text. While I
> can't remember any specific examples, I remember reading docs a few
> times and coming across versionadded statements that were at the
> bottom of their section rather than where they would have naturally
> flowed in the text.
Agreed. It's not just as simple as "strip them out", because in many
cases, the language has been forced into awkward contortions in order
to describe the incremental improvements that have been made.
However, +1 to the idea that we should edit and update to remove the
version tags for versions we no longer support (which is to say, the
1.0 and 1.1 version tags in trunk).
Yours
Russ Magee %-)
Ramiro Morales
Richard has opened ticket [1]14000 for tracking work on this.
One additional question: Should the 'versionchanged' notes
get the same treatment?
Regards,
--
Ramiro Morales | http://rmorales.net
Jacob Kaplan-Moss
> Richard has opened ticket [1]14000 for tracking work on this.
14,000!
> One additional question: Should the 'versionchanged' notes
> get the same treatment?
Yeah, I think so. Remember: we might need to edit/rewrite certain
sections to clean up the (sometimes awkward) wording around version
added/changed stuff. So don't just grep and delete -- a bit of
thinking is still required.
Jacob