I just dropped into this issues queue from the Quicklink block -> suggest documentation improvements ... so I'm not really sure where I am ;) perhaps a breadcrumb or link to the documentation project homepage ... ? So apologies if this is the wrong place for airing these ideas ... pointers welcome.

I'm prompted by my constant use of the 'My Issues' link in the Contributor Links block, and the lack of a similar link to 'My Handbook posts' (etc). To check if there are any updates to my handbook pages, I have to use the User/.../Tracker (buried in the Navigation block under -> Recent posts -> My Recent Posts), which is slow and cluttered with forum threads that I wish I had never got involved with ;) My train of thought gave rise to the following (quite radical) suggestion, which is by no means the only solution to the problem! It promotes the 'context = project' framework of Drupal.org, which IMO works well because you tend to get usergroups accumulating around particular Projects. In a nutshell, I'm suggestion integrating the relevant parts of the Handbook more closely into the Project framework.

  1. Embedded vs Online documentation: Several modules now just use a link to the appropriate Drupal.org Handbook_page instead of embedding static help text into the module download, whilst others provide no online documentation at all. (It would seem like an easy task for developers to C&P their embedded docs into a handbook page ... but this rarely happens).
    If the help docs are maintained primarily online (Drupal.org) :
    a) it removes the burden of maintaining help info in downloadable files,
    b) it means prospective users don't need to install the module to find out all about it ;)
  2. Localise docs to project homepage: If the docs for contrib modules were (by node structure) 'children' of the Project_node 'homepage' (rather than an optional link to the optional Handbook_page ;)
    a) documentation might be regarded as a more integral part of project development and maintenance,
    b) online docs can encourage module users to also keep an eye on the issues queue for updates, bugfixes, etc. (cf release monitor and update status modules),
    c) unresearched issues are less likely if the docs are handy.
  3. Use issue queue for docs maintenance: Rather than comments being attached to the Docs, documentation issues could be reported via the project issues queue, along with other maintenance and development issues.
    a) This way they would get more attention from the people who maintain, develop and use the module. (I don't know how this extra traffic would impact on project-emaillist-subscribers ?).
    b) Issue queues are more maintainable than comment threads.
    c) Issue_nodes already have useful tags for Documention -> bug reports, support requests, and feature requests. All are appropriate to Documentation issues, and IMO many Support Requests are really about Documentation ...
    d) Where issues are concerned with relationships or integration between modules (eg views integration) it might be useful to be able to submit the same issue to more than one project queue ... though I can see how this flexibility could descend into chaos.

This system would work even better if core modules were each given their own Project_node ... ;)

Just passing on my thoughts really - I hope they may be of use.

Comments

josesanmartin’s picture

Component: Customization and Theming Guide » Placement and navigation
Status: Needs work » Closed (fixed)

This is a brainstorming that should be discussed at the documentation list. I'm closing this issue and fowarding the message to the list.

senpai’s picture

To the O.P., here's the link to join the Documentation Mailing List: http://lists.drupal.org/listinfo/documentation