#26003: Add a "how the documentation is organized" explanation
-------------------------------------+-------------------------------------
Reporter: timgraham | Owner: timgraham
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.9
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by EvilDMP):
Maybe it should also include (or perhaps it should be noted elsewhere, in
the "how to contribute to the documentation" section) some notes on how
the documentation in these sections should be be written.
e.g.
* tutorials: don't try to explain how things work ''before'' a step; any
explanations should come afterwards and refer to what has been done (on
the other hand it ''is'' appropriate to explain the nature of the problem
we're solving so that the reader understands what we're trying to achieve)
* how-to: what matters most is what a user wants to achieve, so a how-to
should always be result-oriented rather than focused on details of
Django's implementation of whatever it is we're discussing
* reference: try to keep reference material as tightly focused on the
subject as possible; generally you should assume that the reader already
understands the basic concepts involved, but needs to know or be reminded
how Django does it; if you find yourself explaining concepts, you may want
to move that material to the ''topic'' section
* topic: link to reference material rather than repeating it; use
examples; don't be reluctant to explain even things that you consider very
basic
--
Ticket URL: <https://code.djangoproject.com/ticket/26003#comment:2>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/067.3aff5d3d6dc76a7d7e3c5be5e4010bae%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
