Hi Doug, On 12/18/2015 04:35 PM, Doug Epling wrote: > I filed bug report > > #25952 <https://code.djangoproject.com/ticket/25952> > > but apparently it was in the wrong place.
In case it wasn't clear, it wasn't in the wrong place because it was documentation-related, it was in the wrong place because Trac tickets need to be focused and have clearly-bounded goals such that it's obvious to everyone involved when the ticket has been solved and can be closed. It doesn't work well for large-scale open-ended improvement efforts (these should result in many Trac tickets, each one specific and concrete). > And I referenced this post > <https://groups.google.com/forum/#!searchin/django-users/documentation/django-users/1qHviCZMPJA/_8qVb0YYdhAJ>, > but I was thinking it was this group ... I wonder how that happened? Seems like the user's confusion in that django-users thread could be addressed with a relatively simple patch to the contributing docs. Perhaps you could make a pull request? > So I am hereby suggesting that the road map for the v. 2.0 release > include revamped documentation. Thanks for taking the time to make the suggestion. Since Django is developed by volunteers, there are basically two paths to making a suggestion a reality: 1) Convince at least one of the existing volunteer contributors that your suggestion is more important than the other improvements to Django they are already working on. In this case, this will likely require more hard evidence than you have provided so far that there is a serious problem with the documentation that requires "revamping" them (as opposed to iteratively improving them, which happens daily). 2) Spearhead the work yourself and clearly demonstrate its value in the process. I think that everyone here would gladly welcome whatever time you are able to put into helping improve the docs. > It should begin as soon as possible with the somewhat standard best > practice of collecting "find what you were looking for" or "was this > page helpful" or "rate this page on its organization, clarity, brevity, > etc." data on every single existing page. It certainly seems to me that data like this could be really useful in deciding where to focus documentation improvements. It should be possible to add such a feature to the online docs. I expect it would require significant design and development work to put it in place, which gets us back to options (1) and (2) above. (By the way, this specific idea -- provide a feedback mechanism on the online docs -- _is_ the sort of clearly-bounded task that would make a good Trac ticket, though it might be best to see what feedback others here have first.) > It might also be helpful to evaluate how different audiences access the > docs. Tutorials are great -- module and class libraries, not so much. Are you saying this in general, or specifically in reference to the Django docs? If the latter, how specifically do you think the module and class library documentation could be improved? > With resulting user feedback along with expert categorization of > documentation use cases, as with any writing exercise, there must be an > outline. The existing outline might be a good place to start. > > Oh, and those pesky deadlines, when is v. 2.0 slated for release? 2.0 is scheduled for release in December 2017. Between now and then there will also be 1.10 and 1.11 releases, in Aug 2016 and Apr 2017 respectively, as outlined in https://www.djangoproject.com/weblog/2015/jun/25/roadmap/ Carl -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at https://groups.google.com/group/django-developers. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/5674A416.8080103%40oddbird.net. For more options, visit https://groups.google.com/d/optout.
signature.asc
Description: OpenPGP digital signature
