#26003 closed Cleanup/optimization (fixed)
Add a "how the documentation is organized" explanation
Reported by: | Tim Graham | Owned by: | Tim Graham |
---|---|---|---|
Component: | Documentation | Version: | 1.9 |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Accepted | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
As discussion on django-developers, the documentation structure of intro, topic, ref, howto isn't obvious to many people.
Change History (5)
comment:1 by , 9 years ago
Has patch: | set |
---|
comment:2 by , 9 years ago
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
Note:
See TracTickets
for help on using tickets.
PR