Track progress of building the Help/Docs System [#1549580]

Problem/Motivation

Drupal currently lacks a system for writing really good technical documentation. We should have one, and in particular, the Drupal Documentation Team needs such a system for two purposes.:
a) In-line Help (what the core Help and contributed Advanced Help, and possibly other modules provide within a Drupal site)
b) Official/Curated Documentation (a controlled set of really good documentation about how to use Drupal to build sites).

We have had previous discussions of these two systems on issues:
#1291058: Discussion: Make a curated docs section/system
#1031972: Discussion: What would a better help system for D8 be?
as well as on various groups.drupal.org posts in the Documentation Team area. We came to the conclusion that they should be the same system. This issue is for tracking progress in actually building the system we need.

Proposed resolution

Build a really good technical documentation system. The full specifications for the proposed system are on the Help and Curated Documentation System page.

Remaining tasks

See the full plan at http://drupal.org/node/1095012 for details of these tasks.

Phase 1: Curated/Official Docs System
- Conditional Text module - DONE - http://drupal.org/project/conditional_text - may need some updates?
- Help Entities module and Map entity - Sandbox project: http://drupal.org/sandbox/temaruk/1604964 - needs some updates
- Workflow module for editing/translating permissions - see issue #1283496: Help/Docs system: editorial/translation workflow and permissions as well as the system specs.
- Set up a site (drupal.org or help.drupal.org?), test, and deploy.

Phase 2: Refinements
- Better UI for creating Maps
- Revisions workflow
- Glossary

Phase 3: Inline help
- Help importer/updater client/server

Comments

Comment #1

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 26 April 2012 at 20:36

Issue tags:

+docs infrastructure

forgot the all-important tag. :)

Comment #2

HongPong CreditAttribution: HongPong commented 24 July 2012 at 20:40

A suggestion, not sure where to throw it. One thing I think would help is to auto-form links to directly search help.drupal.org using the content of an error string (stripped of local path) - such that, for example, a complex & inscrutable Mysql error can be searched in the crowd-edited database easily - possibly there could even be a 'suggested official/canonical answer' for some errors. It's the error hunting that kills a lot of momentum & intimidates people about the platform, I think this would help minimize that pretty serious problem.

Comment #3

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 24 July 2012 at 20:46

Interesting suggestion! I think it should be filed as a separate issue though. Right now we don't have a help.drupal.org at all, and I think what you are suggesting is a Drupal Core or contributed module suggested way to handle errors on someone's Drupal installation, right?

Comment #4

HongPong CreditAttribution: HongPong commented 24 July 2012 at 21:22

Yeah that's about the idea. I think it might have to be in core because it would need to jump in and append that kind of search to the error messages. Do you think that would be better under Documentation project or a Core feature request? Seems like it would relate to the kinds of forms of documentation specified in that wiki - it's pretty closely coupled to the idea of the rest of docs evolution, if a different approach.

Comment #5

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 24 July 2012 at 22:11

There's a hook where contributed modules can respond to errors: hook_watchdog(). I think this is not likely to be put into core, so you need to write a contributed module.

It definitely is not a Documentation project request. :) I think there might be a forum for contributed module ideas if you are not a module programmer, or else a group on groups.drupal.org? Good luck...

Comment #6

Renee S CreditAttribution: Renee S commented 10 November 2012 at 00:06

Any status updates from the GSoC progress? Very interested in this! If there's code to test... I can test :)

Comment #7

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 10 November 2012 at 16:06

Hi Renee, and thanks for your interest!

The GSoC project came to a close at the end of GSoC in Aug/Sept, and the project is still in a Sandbox project:
http://drupal.org/sandbox/temaruk/1604964

We should really get that promoted to a real project sometime soon... Anyway, it's usable and if you would like to test it out and file issues if you find any problems that don't already have issues, that would be great! I need to contact temaruk and see what we want to do going forward -- thanks for the reminder. :)