OBSOLETE - Documentation Tools Ideas

This page is obsolete!

This page (and section) are obsolete. As of spring 2014, the Documentation Working Group (DocWG) has taken over the decisions and planning for tools, policies, and procedures for Drupal documentation. The DocWG maintains a section containing the current goals, priorities, and projects of the Documentation Working Group.

Prior content of this page

This is a brainstorm document for various tools and technology to make using and managing Drupal docs better. This is just a dumping ground for ideas that still need to be evaluated and then once a clear path or spec is decided, they should be turned into issues, tagged, and the entry here replaced with a link to the issue.

To find existing issues (which may or may not be related to items here), look for issues tagged 'docs infrastructure' across all projects. To file an issue, start with project Documentation, component "docs infrastructure", and tag 'docs infrastructure'.

On-line Drupal.org Documentation Tools

Authoring

• Allow authors to add images and video to Handbook pages. (#302106: Video training subsite for d.o)
• Add a multiple-entry "Links" field on Handbook pages for links to tutorials, videos, forum entries, etc. Or perhaps this should be done through using a DITA-style "related content".
• Tag a Handbook page as "Stub" (for use in a working queue view).
• Tag a Handbook page as "Tutorial" or "Reference" (for use in end-user views or structure).
• Spell Checker
• Apply semantic tags to paragraphs (rather than h2, h3 etc). For example, if the node is a "Procedure" information type, allow the author to apply a "Step" tag to steps.
• Apply version tags to paragraphs so that certain paragraphs can be displayed conditionally (if the reader is looking at the Drupal 6 version, show all the untagged paragraphs PLUS the Drupal 6 tagged paragraph BUT NOT the Drupal 7 tagged paragraph)
• Add the ability to add index terms and/or freetagging/categories (perhaps in the Wikipedia model).
• Add the ability to edit sections, rather than an entire page

Document User Experience/Participation

• Add a "Subject of This Topic"(?) link field on forum topics (and issues?) that will link back to drupal.org Handbook pages (or other nodes). This would be used to create view blocks on Handbook pages to link to related forum topics (issues), perhaps showing the five most popular topics (with a "more..." link).
• Tag a Handbook page comment as "Thumbs Up" or "Thumbs Down" for inclusion into the page; highlight "Thumbs Up" comments for editors.
• Tag a forum comment as "Solution" (by original poster or editor) and re-sort comments with solution at top or minimize comments not marked "Solution" (or otherwise highlight "Solution").
• Tag a page as a favorite (as the basis for a "My Docs" block)

Structuring / Content mapping / Navigation

• Provide a method to link a module's documentation to its related project page. The module project page has a field to link to the documentation but we don't have a similar functionality on the documentation side to link back to the project page. Right now all we can do is make a manual link in the text. If the project page was explicitly a Related Node we could pull in all sorts of useful information into a block on the handbook page like the Drupal versions supported, whether the module is deprecated etc.(#733908: Add noderef field for project to doc pages)
• Provide a JQuery interface for building document maps (i.e. books) by dragging content from one panel to another (Note, however, that the content wouldn't actually "move". The same node could appear in multiple contexts.)
• Drupal Versions (Handbook page for 5.x, link to same page for 6.x) - should retain version selection page-to-page
  • One possible solution is to use a module similar to i18n (taxonomy_versioning?) with different versions listed at top to switch between related nodes. One issue with that is maintaining book structure (e.g., child page in 6.x with parent page only in 5.x).
  • Another possible solution is to use jQuery to display some part of the content of a single node.
• Provide the ability to display multiple nodes on one page with most of the nodes in collapsed form. So rather than making the user navigate to page after page they would load one page for an entire section. Only the overview node would be expanded by default. Below the overview they can collapse or expand the other nodes (e.g. various procedures) by simply clicking on the headings. This would help the reader maintain context and give a sense of stability (rather than wandering from page to page).
• Audience (for Themers, for Developers, etc., for Beginners, for Advanced Users) - taxonomy terms could be used for more organization similar to Drupal Versions (for example, there could be a "Theming" home page for 6.x, with one version of the page for themers, one version for developers, one version for designers, etc.) - ideally should retain audience selection page-to-page

Management

• Display a list of new pages
• Display a list of edits by new users
• Allow filtering the above lists by subject, so that SMEs can review changes in their field of expertise or editors can monitor certain sections.
• Create a "My Tracked Pages" feature so that people with an interest in specific pages can monitor changes to those pages
• Capture the terms that people use to search the documentation for analysis.

Drupal Help

• Integrate Handbook pages with git (edit a Handbook page and it updates the Help page for a module)
• Neil has written up a large post on changes for api.drupal.org on his blog.
• Contextual Help (Help appearing on a relevant page within a module, and appearing at a particular place on a page)
  • One possible solution is to reload page after clicking on "help" with question marks appearing at appropriate locations, linking to help html files. Would this Help stay "on" page to page?
  • A possible second step is to add question marks/hidden help text with jQuery/AJAX and make help text appear with jQuery.