Proposal to create a Drupal 8 User Manual

Here is some more of the text of the proposal; there are several Appendix sections in the PDF if you want even more details.

Main Idea and Requirements

Motivation

Quality documentation in multiple languages has been identified as a key need for the Drupal community. Another key need is for documentation that would help a “Newcomer” or “Learner” persona make the transition to “Skilled”.

This proposal would result in a concise Drupal 8 user manual, owned by the Drupal project and licensed consistently with other Drupal documentation, which would serve as a learning tool and could be translated into any language.

Requirements - Content

• The audience is site builders and site administrators at the “Newcomer” or “Learner” level in the new Persona system. The manual provides the information these people would need to become “Skilled” Drupal users.
• The manual covers the tasks that site builders and site administrators would need to build and manage typical Drupal sites: installation, updates, site building, configuration, and administration. These tasks can be in the Drupal user interface, on their hosting/server (e.g., setting up Cron), and possibly with tools like Drush.
• Content selection is based on building/managing typical Drupal sites, not limited to Drupal Core, and not necessarily covering every module of Drupal Core.
• The manual includes background information and terminology as necessary, so it can stand alone without referring to Drupal.org pages or other references.
• The manual is concise, rather than attempting to be a comprehensive guide to everything you can do with Drupal. It does not cover programming, or generic web topics like information architecture and search engine optimization, but concentrates on how to do the tasks a typical Drupal site builder or administrator would need to do.

The proposed outline for the guide is in Appendix A.

Requirements - Functionality and Technical

The proposed manual:

• Has multiple ways to navigate and find information: table of contents, related topic links, keyword index, search.
• Follows modern technical writing best practices for writing style and splitting the text into small, cross-referenced topics (split into Concepts and Tasks).
• Can be translated into all languages Drupal supports, via localize.drupal.org or at least by the existing language communities.
  Is exportable to PDF as a complete book, and possibly to other e-book formats. Ideally, it should also be displayable (in multi-page HTML format) within a Drupal 8 site and on a *.drupal.org site.
  Stores its source in a Git repository (limited commit access and editorial control).
• Is editable either using a plain text editor, within a Drupal 8 site, or on a *.drupal.org site. The editing mechanism and format should be easy for tech writers who are not necessarily PHP programmers.
• Has standard Drupal content licensing (Creative Commons).

Platform/Technology

There are several options for the technology that could be used to create this manual and satisfy the technical requirements. The proposed solution is to write the manual using AsciiDoc (http://www.methods.co.nz/asciidoc/index.html), which is an open-source, GPL-licensed, plain-text-with-markdown format that is easy to edit and learn, and is used by major players in the commercial technical documentation industry, such as O’Reilly.

Once the source is written in AsciiDoc, it can be processed to various output formats, such as PDF, HTML, and many e-reader formats. It can also be displayed in a Drupal site, using the “AsciiDoc in Drupal” module (which is currently a sandbox project for Drupal 7: https://www.drupal.org/sandbox/jhodgdon/2265553). PDF and e-book document readers generally have search capabilities, and Asciidoc includes capabilities for automatically generating an index and table of contents (from notations in the source), and cross-references between sections. Editing can be done using any plain-text editor; the AsciiDoc in Drupal module also has a visual editor that can be used from a Drupal site, with preview capability.

The source for the manual itself would be maintained in a drupal.org project git repository.

The AsciiDoc in Drupal module would also need to be promoted to Full project status and ported to Drupal 8. The module is fairly simple (AsciiDoc tools do most of the work), so this will not be difficult. Some simple scripts may also need to be developed to process the source into the various output formats; instructions and sample scripts already exist in the AsciiDoc in Drupal module.

Getting it Done

Initial English Version

We are requesting funding from the Drupal Association for two or more writers and editors to produce the English version of the Drupal 8.0 manual. Given that much of what we would need to cover is already documented on pages under drupal.org/documentation, this job would be partly taking existing material and organizing it into a well-written and consistent manual, and partly writing new documentation if that would require less work for a particular topic. For each section, one person would be writing/compiling, and a second person would be editing.

Budget

Our estimated budget is 100 hours for writing/compiling/indexing, 40 hours for copy and technical editing, and 10 hours for a novice user to test it, based on an approximately 50 page PDF book with an index, and with screen shots included where appropriate. The plan would be to do the novice user testing with volunteers at a sprint, for instance at a DrupalCon.

Translations

The language communities for Drupal would be expected to either translate the manual via volunteer labor, as they now do for Drupal Core and Contributed modules and themes, or request funding from the Drupal Association to translate it.

Ongoing Maintenance

Since the manual will be a standard Drupal.org project, volunteers will be able to file issues and make patches, for smaller updates (like fixing bugs, typos, etc.). They could also contribute new sections, so that the manual can expand over time, although this will need to be managed carefully. The Maintainers will review/commit patches on a volunteer basis, just like other Contrib modules. The Documentation Working Group will provide volunteer maintainers for the tool chain, including the AsciiDoc in Drupal module and any necessary scripts.

For larger updates, like for the 8.1.x or 9.x versions of Drupal, we would probably need to seek funding again, depending on how much of the manual needs attention and updates (i.e., depending on how different the installation process and administrative user interface is between versions).

I love this idea. I know the Symfony project's downloadable ebook (https://symfony.com/doc/2.7/book/index.html) and Magento project's user guides (https://magento.com/help/documentation - bottom of page) were major helps in getting started with using the software and would love to see something similar for Drupal.

Just one comment about the size and time estimate cited in the proposal. I believe 50 pages and 150 hours is way underestimating the scope of the project....even just as a start. 30-50 pages could easily be devoted to just Views alone. 200-250 pages would probably more inline as a guestimate for an initial administrators/site builders ebook.

Thanks for proposing this!

I think this is generally a great idea. There are several places, where the translatability of this is highlighted as a differentiating factor. However, how would that technologically work is not addressed. How would localize.drupal.org parse that AsciiDoc? How would images be swapped for translated screenshots? Where would those screenshots be hosted? Localize.drupal.org does not allow for or handle image uploads as translations for example, that is totally outside of the realms of the service. If the manual is to be translated to Spanish, I don't think you would want to see English screenshots there? Especially where it says "look the installer is in Spanish".

I like the idea for the content, but I'm generally -1 to rolling yet-another-drupal.org-specific solution for an already solved problem. I suggest ReadTheDocs and markdown. You can version the documentation (both in terms of committing changes to the documentation, and in terms of maintaining different sets of documentation for different versions of Drupal), translate it, export to PDF, and the entire toolchain is open source. It's all built on mkdocs, so if we wanted, for instance, epub or mobi support in the future, it's as simple as opening a PR. Note that if the lack of epub/mobi support is a deal breaker at this point, I'm happy to work on it. There are a number of existing python libraries that will handle the heavy lifting.

Note that while readthedocs is typically used with Github, we don't have to do that. You can point the readthedocs project at a Drupal.org git repo and it'll work just fine. Maybe you can even talk the infrastructure team into setting up a webhook so that the documentation rebuilds whenever you commit to the repo.

This sounds amazing. I wanted to point to a funded Kickstarter project by OSTraining. They are going to create 50 free and downloadable Drupal 8 training videos. See: https://www.kickstarter.com/projects/stevebure/drupal-8-training-videos-...

In the campaign you can see the list of topics they are planning to cover in the videos. Would it be worthwhile to attempt to integrate at least some of the manual with some of these videos on corresponding topics?

Joe Saylor
Drupal Association

I am very interested in helping with this. I have limited time that I could volunteer but would be very interested in trying to find some funding to support this.

On my blog (http://denverdataman.com/blog) you can see lots of writting samples and I would be glad to share some of the manuals that I write on a regular basis.

A couple weeks ago at DrupalCon Los Angeles I, along with Amber (@amberhimesmatz) Matz, and Greg (@heyrocker) Dunlap gave a presentation titled, "Lets Talk Documentation". Which talks a bit about this proposal, as well as a number of other ideas for improving documentation on Drupal.org. You can watch the video of the session and much of the conversation that ensued after on the DrupalCon Los Angeles site. I think it provides some good context for this proposal.

I think one thing to keep in mind here is that we're not proposing to get rid of the existing community documentation and related tools. But we would like to see some of the content that currently exists in the handbook managed in a different, more curated, way. I don't know exactly what that looks like, but we would eventually need to figure out how these two live together. And, how we deprecate existing handbook pages in favor of the proposed user guide.

I can also see a future in which there are additional guides that are written in this format. Like a module developer guide, and themer guide. Which would be amazing.

But, there will also always be a need for documenting modules in Contrib, best practices, and all kinds of other things that don't lend themselves to this proposed format quite as well.

Going back to the presentation linked above. In that presentation I tried to outline some of the pain points we're experiencing in the documentation efforts right now. And here's how I think adopting an approach like this, for at least the really high-touch stuff, could help to solve some of those problems.

With an approach like this, both as it's initially written, and as it's maintained over time, updates to documentation are reviewed for style, voice, accuracy, and grammar. And probably a lot of other things too.

Curation helps to ensure that we're not missing important topics or pages and that content is presented in a way that flows appropriately. Right now, we have a tendency to write documentation for whatever thing we happen to be working on the time and then figure out how to shoe-horn it in wherever it seems to fit the best. This leads to outlines that don't have any natural progression to them, and in a lot of cases are missing important steps all together. Not a great first impression.

Documentation can be branched for different versions of Drupal core. Right now we struggle to identify which pages are relevant to which versions of Drupal core. Sometimes there are two pages that have almost identical content. And in other cases we've got one page with information for 2 or more versions of Drupal on the same page and it can be challenging to figure out which version the content applies to.

Personally, I think one of the biggest wins to using VCS system for documentation like this is that it allows us the opportunity to discuss changes. Right now, it's easy enough for anyone to click edit and change something. But this can be a hurdle for people who are not 100% confident in the change. And it can also be a really frustrating experience to come back to a page that you've spent hours working on and find that someone has completely changed it.

The fact that this proposal is seeking to get some sort of funding, and starting with that in mind instead of just trying to once again create something purely on the goodwill of others is an important part of this that is easy to overlook.

I could go on for a lot longer about the potential benefits of something like this, but I'll leave it at that for now.

I also wanted to recognize that ideas like this have been brought up before, and in the past I've been a somewhat vocal proponent to the idea of removing the edit button from documentation. But over the last year or so I've started to realize that I was maybe just holding on because change is hard. The truth is, if we want to create better documentation, that eases the learning curve, and gets more people using Drupal, we need to apply the processes required to make sure our documentation is of the highest quality.

Needless to say. This gets a big +1 from me.

And, I'm also very interested in helping out with the creation of a user guide. Both because I think it would be great to have, and because I'm curious to see how it goes and if this ends up being something that can be applied in other areas as well.

I have quite a bit of experience working on Drupal documentation (and I'm part of the DocsWG), and as a trainer for Drupalize.Me I've had lots of opportunity to teach people Drupal and related things. Doing so has given me a pretty good handle on what it's like to be new to Drupal, and also where people tend to get hung up in the learning process. I think that I'll be able to work on this without the need for additional funding as I can most likely get at least some work time to do so and can volunteer some time as well.

Great idea!
Sounds exciting and I am open to join my hands in this initiative.

This is a great idea! I am really keen to be involved.

• How much time do you have (July-September 2015)?

I can commit to 4 hours a week.

• Would you need funding, or will your employer sponsor at least part of your time?

I have a supportive employer, so I can likely do some work during paid time, and some during volunteer time. I won't need any funding.

One question I have is: will employers be credited (in the manual, or in some other way) for providing paid time? That makes it easier for me to justify.

• Are you interested in participating as a writer or editor (see proposal)?

I would be happy to do either.

• Can you provide a technical writing sample?

Here's a link to my Master's thesis: https://klena02.files.wordpress.com/2010/09/documentorientedpersistencew...

I discussed the manual with my colleagues Diana, Kelly and Laura and we really would like to contribute to this effort. We could sponsor both Diana's and Laura's half-time (20h/week) involvement in July and August (there are a few holidays for both).

+1 from me, this is a great idea and would love to participate in the testing somehow.

As others have mentioned, one of the concerns I have is how lengthy this manual could potentially be and agree with @eojthebrave that we have to be really careful and only include that content that allows the user to complete the task described.

What about a shorter, glossary like quick-read? Honestly, the attention span people have is so short, a high level doc (in addition to, instead of, that this one starts as?) might also be something to think about. It would be awesome to be able to point to a shorter guide when providing training to clients. I think our clients would really appreciate that.

This discussion is all about building a brand-new, sparkling set of documentation for Drupal 8--on top of a mess of outdated and jumbled documentation for Drupal 7, 6, and whatever else is still there from before.

The biggest problem that gets in the way of people learning from d.o documentation is having to wade through various pages that may be no longer accurate because new functionality has rolled out.

If we turn at least half of our attention toward the existing Drupal 7 documentation to clean it up, we will accomplish two things: provide the support that new site builders will need for the next year or two, and provide a model for the new Drupal 8 documentation using the existing content. No lore ipsum here!

I think a 50 page PDF (and related other versions) is the max that an intro document, with installation instructions, should require or have. The more too read, the less gets read.

Mention views, module creation, etc., but don't discuss them any more than necessary to introduce the novice to what these are, when and why they should be used, and where to find out more about them. Anything more than that detracts from the introduction and implementation of the basic Drupal that I think must remain the focus of this manual.

Even multilingualism, which is often required (I work in Canada on a site in English and French) and therefore must be part of an initial install, should be handled elsewhere. Introduce it, indicate it must be addressed from the outset when installing a site, and point to more detail.

In other words, focus on the main task of installation.

Step one is to build an outline.

I'd love to help (and I don't need any money). I have lots of experience writing and editing, have authored books in the past (but none in the last 20 years), and am a retired IT manager now acting as a webmaster for a small not-for-profit association (small, yes, but they hold a large annual conference, do research, and publish a science journal. i.e., lots of quality material goes up on their site.).

• Ed Brandon

I started an outline node - https://groups.drupal.org/node/470913
I have not put any content in this yet. I will try and work on this a bit today but we have a node.

-Steve

I started an outline node - https://groups.drupal.org/node/470913
I have not put any content in this yet. I will try and work on this a bit today but we have a node.

-Steve

There have been a number of comments so far related to defining scope for this project. Something that I think we all agree is important. Having a clearly defined scope will help to ensure that we're covering the right material, and that we have a tool of sorts for saying, "Sorry, but that is out of scope."

So with that in mind. Here's what's been defined as scope thus far.

The audience is site builders and site administrators at the “Newcomer” or “Learner” level in the new Persona system. The manual provides the information these people would need to become “Skilled” Drupal users. You can learn more about personas that this is based on here: https://www.drupal.org/personas. So really, our target would be to write to the learner persona, and help give them the skills needed to progress. Or, at least to help them to better understand what it is they don't know yet, and where they can continue to develop their skills.

The manual covers the tasks that site builders and site administrators would need to build and manage typical Drupal sites: installation, updates, site building, configuration, and administration. These tasks can be in the Drupal user interface, on their hosting/server (e.g., setting up Cron), and possibly with tools like Drush.

Content selection is based on building/managing typical Drupal sites, not limited to Drupal Core, and not necessarily covering every module of Drupal Core. We could work to define a specific example use-case of Drupal that highlights important concepts and functionality, but doesn't necessarily cover every little detail. Perhaps using one of the ideas previously developed for Snowman. Which attempted to come up with example sites that illustrate Drupal core's strengths. But without the Snowman limitation of core modules only.

The manual includes background information and terminology as necessary, so it can stand alone without referring to Drupal.org pages or other references. Which is to say, everything required to accomplish the defined task is present in the manual. The manual can however link to other reference material on Drupal.org to help one further there knowledge related to any system or concept being covered.

The manual is concise, rather than attempting to be a comprehensive guide to everything you can do with Drupal. It does not cover programming, or generic web topics like information architecture and search engine optimization, but concentrates on how to do the tasks a typical Drupal site builder or administrator would need to do.

Does this scope seem adequate enough to help ensure the manual doesn't spiral out of control and try and cover everything under the sun? Does it give us the authority/tools wee need to answer questions like:

• Is it okay to skip this covering topic X?
• Is our coverage of Y complete?

And other similar questions that we will undoubtably have to address as we begin to write a manual and everyone starts weighing in with their idea about what should or should not be included.

Or. Is this not detailed enough and we should be seeking to define stricter scope/requirements before we begin writing?

I just read through all of the great new comments on this... THANKS everyone!

I haven't replied to each one individually, but I'm incorporating your suggestions into the Proposal and keeping a list of all the people who've expressed interest in helping out.

As noted by ifrik above:
- We're asking for people to comment between now and June 19th
- At that point, the Documentation Working Group will be meeting to discuss all of your suggestions and Next Steps.

So... When we started thinking about this proposal, we were thinking we'd apply for funding and have a very small group of people working on it. But it's looking like a LOT of people would be able and willing and excited to be involved, which is really great! This also means that we'd need to change the way we work on the project, if we still want to end up with a coherent, concise guide and not a copy of the existing Community Documentation (which, as we all know, has its downside in lack of coherence etc.).

I think if we go with the tide here and have a lot of people working on the project, we'll need to (a) set up some templates and guidelines and outlines before we start and (b) have a designated project manager (or two), who will play a role similar to a Drupal Core branch maintainer: making sure that anything added to the guide fits within the constraints. The project manager would need to coordinate the following, I'd think:
- Project startup: coordinate with Docs WG on templates, structure, outline, toolchain, Git repo, etc.
- Weekly group meeting (probably in IRC)
- Progress reports
- Volunteer coordination - writers, editors, testers
- Quality control - making sure what is produced is staying within the templates/structure/outline/guidelines [separate from editing, which will also need to happen]

Thoughts? [Note: this is just me rambling; haven't discussed this with the Docs Working Group yet! Not officially part of the proposal at this time.]

Based on learning Drupal, teaching Drupal, contributing to drupal.org documentation and writing how-to books, you need a leader to coordinate the activity, plan what is needed, and to find the right people for each area.

First, you need to differentiate between reference material, tutorials, how-to content, and the WWWWH material. Here are my notes updated for Drupal 8.
https://petermoulding.com/drupal-documentation-%E2%80%93-time-for-a-rewrite

The Docs WG had a mini-meeting today... Joe and I have the opportunity to go to the Twin Cities Drupal Camp and hold a sprint later this month, and we decided to go for it! See
https://groups.drupal.org/node/471268
for details. So we're really going to do this!!

Note: This page is still open for comments until June 19 and we'll incorporate as many suggestions as we can into the initial outline, guidelines, etc.

Hi folks,

Thats a super nice idea, I'm kindly still a middle-beginner in Drupal but I hope I can help the community to build this manual. I'll follow the topic and post anything wich could help you out.

PS : If I do understand the project right, it would require some traduction in multiple languages. I'm French so I guess I can help with the French part, Idk how do you proceed about that ?