[documentation] Feature requests and ideas

[José San Martin]

Cleaning up the issue queue.
I've found this issue - http://drupal.org/node/133988 - with some
ideas and I really don't think issue queue is a nice place for
brainstorming. So, I'm closing the issue and opening a discussion
thread here. Note that these are NOT my opinions, it's just a follow
up.

ze sanmartin

------------------------------------------------------------------------------------------------------------------------------

integrate documentation into contrib projects
by JohnG (http://drupal.org/user/19957)

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 ;)

# 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.
# 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.