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 %-) --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
