Opened 8 years ago

Closed 8 years ago

Last modified 8 years ago

#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 Tim Graham, 8 years ago

Has patch: set

comment:2 by Daniele Procida, 8 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

comment:3 by Tim Graham, 8 years ago

I've updated the pull request as you've requested.

comment:4 by Tim Graham <timograham@…>, 8 years ago

Resolution: fixed
Status: newclosed

In df3d5b1d:

Fixed #26003 -- Added "how the documentation is organized" sections.

Thanks Daniele Procida for coauthoring.

comment:5 by Tim Graham <timograham@…>, 8 years ago

In fd830ac8:

[1.9.x] Fixed #26003 -- Added "how the documentation is organized" sections.

Thanks Daniele Procida for coauthoring.

Backport of df3d5b1d73699b323aac377dffab039dca26c1e4 from master

Note: See TracTickets for help on using tickets.
Back to Top