Discussion: Make a curated docs section/system

Here are some principles to start the discussion.

a) Curated docs should be task-oriented and built of atomic topics (following the ideas, and as much as possible/practical, the structure, of DITA).

b) They should be limited to the core, central tasks that most users would need to do to build and manage a Drupal site: installation, update, basics of site building, configuration, and administration.

c) They should have several ways to navigate and find content:
- Table of contents/outline (maybe multiple outline capability?)
- Keyword index that is built carefully
- Search

d) They should be written with conditional text so that they can be updated for new versions of Drupal and other modules, without introducing major clutter.

e) Editing should be limited.

We have discussed whether it would make sense to start the Curated Docs section with an existing book, such as Johan Falk's "Drupal 7 Essentials" (if it is feasible with copyright restrictions etc. -- the Drupal Docs team needs to have the ability to edit/update/add to the docs going forward without restriction).

Advantages of this approach:
- Content is already written.

Disadvantages of this approach:
- Books are not written in DITA-like topics currently or in HTML, so some adaptation will be necessary.
- We may have copyright/ownership issues and struggles.

Another thought would be to make this "curated docs" section the same as the online editing area for the proposed Drupal 8 core inline help system -- i.e., we would start this curated docs section by writing the tasks corresponding to core module tasks, and build from there (adding the install guide etc.). See http://drupal.org/node/1095012 for an outline of what this proposed system would entail.

Advantages of this approach:
- We would definitely own the content.
- The proposed structure for topics etc. for the Help System docs is pretty much what we want for the curated docs (DITA-like topics, conditional text, multiple outlines, keywords, etc.)
- The structure should be close enough to DITA that we can use DITA tools to export the docs in other formats (PDF books etc.).
- Would combine the "curated docs" with the "available for import inline docs", and reduce duplicated effort.

Disadvantages of this approach:
- The content isn't written yet (although we should be able to draw from the current inline hook_help and existing Community Docs pages)
- Inline help is probably more module-oriented and module-organized than we would want, although the proposed system includes ability to make multiple outlines, so that mitigates this factor.

RE #4 - the new proposed inline help system is planned to allow module maintainers to designate who can edit their official docs (using the online editor on help.drupal.org or wherever it is). So if we use the same system for the "curated docs section", we might want to propose that this be a designated subset of these docs. I don't think the "curated docs section" would necessarily be limited to Drupal Core though -- for instance, can you imagine having an intro to site building and not mentioning Views?

RE #5 - Have you read and understood http://drupal.org/node/1095012 ? I would appreciate it if you could read it before proposing adopting particular tools -- at least understand what the objectives are of that project. Our objective is not to have DITA. Our objective is to have a Drupal help system, and I don't believe that all of our objectives can be met with DITA. At a minimum, we need the docs to be stored and edited within a drupal.org site (not in XML files), and we absolutely do NOT want to involve Git in editing/writing the docs.

RE #8 A - When I said "the core, central tasks" in comment #1 (b), I didn't mean "Drupal Core" only, I meant "core" in the normal English sense of "central and essential". Sorry for the confusion - I do agree with you there.

RE #8 B - We already have a way for people to contribute whatever documentation they want to -- it's called the "Community Documentation" (or will soon be, if the current proposal in #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained. is adopted. The proposed Help system specs also already say that contributed module maintainers can define who the maintainers of their official documentation on the official site would be.

We probably also would need to have an issue queue for these help docs, and one of the functions would be to petition for Community Docs to be adopted into the Official Help Site (or whatever we call it).

RE #11 - Good point! So here's a (partially) new idea.

What we want for the Official Help System is for each Help Entity Item to be associated with a single d.o Project, and for each Project to be able to designate who has permission to create/edit its help entities (help entities consist of the different types of topics, as well as outlines/maps).

So the Documentation Project could maintain set of help entities on the Official Help System site, which would be the Official Drupal User Guide (or whatever we want to call the "curated docs"), and which would consist of the basics of installing Drupal, building a site, and administering it (using a variety of core and contributed modules). And then the Views Project could have its own set of documentation, which might go more into depth about the details of using Views than we do in the User Guide (but their outlines could pull in some Documentation Project help topics if appropriate). And the Zen Theme Project could have its own set of documentation, which would describe how to build a theme using the Zen base theme, but it might pull in some of the Theme Building doc topics (I'm assuming that the Doc Project might have a theme building section too).

And if someone wants to create a new project just to maintain some documentation, I don't see a problem with that? We already have an approval process for projects (I admit it is fatally flawed, but that's a separate issue), and in theory anyway, someone could potentially apply for a documentation-only project (we already have Module, Theme, and Install Profile projects, so why not Documentation projects too?). Maybe the Theme Building Guide would be a separate doc project, for instance?

How's that for an idea? :)

Great discussion by the way. Thanks everyone for thinking critically and carefully about this!!!

#15 - valderama: The processes of building a site in Drupal 6 and Drupal 7 are substantially the same. Really the main differences are the Overlay and that some of the user interfaces have been cleaned up a bit. And most of the nav paths are different.

We also need to think about maintenance though. If I have to go to several places to fix some documentation, because it is separate for d6/7/8/etc., then it is harder to maintain. And where do you draw the line? For instance, some contrib modules add new features or make UI changes in minor versions, and you really don't want to have them completely rewrite their docs every time something changes.

We should be able to make it so that a user can say "I'm browsing for d7" and they only see the d7 portions of the page, too, which should make it easier to deal with. That's a proposed feature on the (already built) conditional text module.

Adding new tag. These issues tend to get moved to other issue queues, so we need a unifying tag in order to find them consistently.

Actually, we do have a page describing how contrib module maintainers should document their modules. I don't have time to find it at the moment -- it's in the section on how to contribute a module to drupal.org. This should be added there, and it should also be moved to a separate issue in the Documentation project (with tag "developer") please.

Here's the page I was thinking about:
http://drupal.org/node/161085
I think it covers most of what you are talking about... getting module maintainers to follow that guideline is another question!

Anyway, bcobin: Please read that page over from the perspective of a module user, if you have time, and see if there is anything missing. If so, please go to
http://drupal.org/node/add/project-issue/documentation
and add a new issue. Explain what you think needs to be added or modified, and tag the issue with "developer". Thanks for your feedback!

Some new (or partially new) thoughts on this (or maybe this is a proposal):

1. The curated online docs site is the same as the site for editing the inline drupal help topics (see help system specs). Tentatively called Official Help Site (OHS) for this discussion.

2. Each topic page and outline on the OHS is under ownership/maintainership of one drupal.org Project. Each d.o Project can designate docs maintainers (much like now they can designate committers and issue queue maintainers), and they will have editing control over the topics they own/maintain. (There are workflow specs in the help system specs that goes into more detail on this idea).

3. The Documentation Project will own/maintain the main "user guide" (working title) topics, as well as the inline help for Core modules (which will have some overlap). Or we might want to create a couple of "official" docs-only projects, such as one for the "beginner tutorial", one for the "install guide", one for the "theming guide", etc., each with their own issue queue and team? Maybe best as one team, I'm not sure. And we probably don't want free creation of docs-only projects, but we could have an approval process for this. I doubt many groups will be clamoring for a docs-only project, since they can have more freedom to write on the Community Docs site anyway -- the OHS will be more rigid on its atomic nature, etc.

4. While all topics on the OHS will be importable as inline help into a Drupal site, and all will be displayed to visitors to the OHS as online help, some topics are more suitable for inline help and some more for online tutorials (e.g., the "What does the block module do" is more important for inline help, while "planning your site" is more likely to be in a tutorial). We can designate this by creating outlines that are marked as 'inline help', and others might be designated as 'tutorial'. (We plan to have multiple outline capabilities for the help system.) That way, some topics (such as "Creating a new block") could be used in both sections (reuse!), but only the most relevant ones might be imported into a site as the Help system, and people following a tutorial wouldn't need to read the irrelevant stuff.

5. Any topic on the OHS would be eligible for translation by the internationalization teams.

Some advantages of this proposal:
a) A contrib module's docs team has one single place to go to edit their documentation (including online and inline help).
b) Topics can be reused in both online tutorials and inline help.
c) Infrastructure can be reused between the curated docs system and the inline help system (the only additional thing we need for inline is a way to import topics).
d) We can have translated user guides as well as translated inline help.

Regarding the downside in #23 - I think the main adjustment will be in thinking, rather than markup. The topics should be HTML markup as usual, with perhaps a slightly different input format but I don't think it will be all that different. There will be some meta-data fields (like a required short summary, modules referenced, keywords, etc.); some of them will be different from the community wiki, but I think they will not be a huge burden... rather that they will aid people in making good choices about how to structure their documentation, hopefully!

The thinking adjustment will be in making pages small and atomic, and separating out into tasks, concepts, reference, glossary, outline rather than melding them together into large spaghetti pages. But this type of separation is generally considered to be a good idea for technical documentation (which is why it is also the core idea of DITA), and I do not think it will be a *huge* burden. We'll definitely have to have a "contributor's guide" section on the help site to explain what to do, but I think people will get the idea without too much trouble.

I really don't want it to be a huge burden or difficult to master -- but there is some adjustment necessary if we want this to be a quality set of official documentation. The trick is to make sure the burden is just what is absolutely necessary to achieve our goals, and no more.

Good idea! It should certainly be thought through.

Thanks, that looks like just what we need! Except we'll need to know who they've designated as "docs maintainers", which doesn't exist yet, and would probably be "authenticated users" by default. :)

Sounds like a good idea.

Also, at BADCamp when I was discussing this plan/idea with people, someone (can't recall who, sorry) suggested that we could build the Curated Docs site first, and add the ability for topics to be imported as inline help later. That would make getting this site up and running soon more feasible, since the only missing pieces would be the workflow stuff (which I don't think is all that hard to write) and the help entities module (which isn't difficult at all).

OK, let's call that a plan! I think once we get the community docs stuff sorted out, we should be able to start on building the curated docs site very soon (if we can get infra team on board).

Tagging so it doesn't get picked up by #1421874: [meta] Documentation Issue Queue Cleanup

I'm going to close down this issue, which had a great discussion, and now we have really solid specs on http://drupal.org/node/1095012 for the combined Help/curated Docs system that we want to build.

To track the progress of building this system, see new issue:
#1549580: Track progress of building the Help/Docs System