Hi guys, I raised a ticket about doc improvements too: http://code.djangoproject.com/ticket/11152. I'm also happy to provide patches to make django's docs play nice with others.
Ben 2009/7/6 Russell Keith-Magee <[email protected]> > > On Sun, Jul 5, 2009 at 4:47 PM, Amit Upadhyay<[email protected]> wrote: > > Further, its difficult to locate information about generic relations on > any > > of the following pages: > > > > http://docs.djangoproject.com/en/dev/ > > http://docs.djangoproject.com/en/dev/topics/db/models/#topics-db-models > > > http://docs.djangoproject.com/en/dev/ref/models/fields/#ref-models-fields > > This is because Generic Relations aren't part of the Django core > fields. They're part of the contenttypes contrib application. As such, > they are an extension that may be useful, but not really something > that should be confused with the core fields. An appropriately worded > note/sidebar that refers to generic relations might be appropriate, > though. > > > Doing search on google leads to > > http://www.djangoproject.com/documentation/models/generic_relations/, > which > > is not really the right place to learn about them, only some example > usage. > > Google has indexed what it thinks is significant, based on PageRank. > I'm guessing there are a lot of people with backlinks to that page, > since it is a page of historical significance (you will note the > www.djangoproject.com/documentation/models URL, which is part of the > old documentation structure). > > > The actual information is available on "Content Types" page > > [http://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/], which > is > > very non intuitive. > > It may not be intuitive why a page on ContentTypes contains > information on Generic Relations, but this is the page that is > returned as result 1 when you use the (Google powered) search function > on docs.djangoproject.com. and GR's are mentioned in the table of > contents for the page, and in the search result summary. > > > Recommendations: > > > > Make model fields reference page > > [ > http://docs.djangoproject.com/en/dev/ref/models/fields/#ref-models-fields] > > either include these fields, or link to the content type page where they > > are, currently searching on that page for GenericForeignKey gives no > > results. > > Make generic relations a top level item on documents page > > [http://docs.djangoproject.com/en/dev/] > > > > I generally get the feeling that there are bit too many pages, we can > make > > the entire thing better by clubbing related things together. > > I disagree. "clubbing related things together" is a bit of a naive > statement here - "related" by what measure? By purpose? by audience? > by feature? Each of these will require a different organization, and > each is a perfectly valid way of organizing documentation. > > > and we can identify the > > following main class of consumptions: > > somebody learning django -- devote a page for them > > somebody writing models, containing db, queries, models, fields, custom > > fields etc > > somebody writing views, contain request/response details, cookies, meta, > > urls, shortcut functions etc > > somebody working with templates, standard tags and filters, writing own, > > shortcuts > > deployment > > installations: one page for windows, another for mac etc. > > To a certain extent, this is what the docs.djangoproject.com homepage > tries to do. The documentation tree contains: > - introductory notes > - a tutorial > - topic guides for various features of Django > - In depth references for various featues of Django > - Howto guides for specific topics > - Notes on installation > - Multiple FAQ lists > > This structure is reflected in the source - and therefore the URL - > hierarchy. The howto, reference and topic sections are essentially > grouped by feature within this hierarchy. > > This tree is then complimented by task-based indexing on the homepage > e.g., "The template layer: for designers", that links into key > sections of interest in the topic guides, references, and howtos. > > One of the problems is that for any given topic, there isn't always a > full set of reference, topic, and howto. This is obviously something > that could be improved, but it isn't fixed by dumping content onto a > single page. Any contributions to fill out the missing pieces (or > reorganizations to put the existing pieces in more appropriate places > in the topic/ref/howto hierarchy) are most welcome. Suggestions for > new top-level groupings, or modifications to existing groupings are > also welcome. > > >> I find http://docs.djangoproject.com/en/dev/topics/db/ page quite > >> inadequate. If I was doing that page I would include links to the > following > >> pages, along with the ones that are there: > >> > >> (Model Field Rerence, where all standard fields are listed) > >> http://docs.djangoproject.com/en/dev/ref/models/fields/ > >> (Writing Custom Model Fields) > >> http://docs.djangoproject.com/en/dev/howto/custom-model-fields/ > > This essentially reinforced my previous point. You have referenced > three different sections of documentation here: > - A topics guide (/topics) > - The reference (Everything you need to know about custom fields) > - The HowTos (Howto build a custom field) > > These _should_ contain three different aspects of detail about model > fields. They are complimentary, and should be cross linked. > > >> The content of these pages used to be clubbed with > >> http://docs.djangoproject.com/en/dev/topics/db/models/, which was very > >> handy, I have to open just one page, and all relevant information for > >> writing models is there, now I have to keep on searching. So I would at > the > >> least add the links to the above to pages prominently on the top or on > the > >> sidebar, as of now they are quite difficult to find. > > Since the days of old, we have added a lot of extra documentation. In > the interests of organization, the single monolithic page has been > split. Rather than try to manage sub-sub-sub-sub headings on a single > page, we have introduced a hierarchy of pages. > > >> Please merge the three pages together, or at least put the cross links > >> prominently. > > Merging - no. Cross linking, yes, in conjunction with relevant > additional content: > > - The HowTo should have a step-by-step walkthrough of the process of > building a specific custom field, with a link to the topic guide and > reference. > - The topic guide should have a broad description of the issues > surrounding custom fields, with a link to the reference, and the howto > - The reference should have a complete rundown of the spec required by > a custom field, with links to the topic guide and howto. > > In some cases, the content doesn't exist yet. In some cases, the > reference content may be in the topics section (for historical > reasons, or due to oversight). Part of what is needed is an audit of > what is missing, as well as proposals for what should be reorganized. > > >> Will create a patches if given a go ahead. > > Always welcome. > > Yours, > Russ Magee %-) > > > > -- Regards, Ben Ford [email protected] +447792598685 --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/django-developers?hl=en -~----------~----~----~----~------~----~------~--~---
