[[manage-notes]]
=== Notes and Lessons Learned

[role="summary"]
Notes about the User Guide project, which may be useful for groups wanting to
set up a similar project in the future.

This section contains some notes about how we set up the User Guide project and
managed it. It is intended for groups who want to set up a future project, and
will be updated as time goes on.

On this page:

* <<notes-personnel>>
* <<notes-project-repo>>
* <<notes-file-structure>>
* <<notes-tracking>>
* <<notes-contributor-guide>>
* <<notes-communication>>

[[notes-personnel]]
==== Project personnel and recognition

This project was realized with the following participants:

Volunteer coordinator::
  Led meetings, provided status report, assigned and tracked tasks
Content coordinators::
  Three people who oversaw quality and adherence to standards
General volunteers::
  These come in the forms of writers, editors, testers, and translators. They
  wrote the topics and did most of the editing, testing, and translating.
Indexer::
  We considered hiring the expertise of a professional indexer to improve the
  index, but were able to find a skilled volunteer in the Drupal community by
  posting on groups.drupal.org/documentation.
Paid copy editor::
  We decided that for the sake of unity of voice, it would be good to hire
  a copy editor to do a final edit of the guide. A sponsoring company paid
  for this; we also considered applying for a Community Cultivation Grant
  from the Drupal association.

To recognize the contributions of all of these people, we:

* Added names and links to an _attributions.txt_ file for guide-wide
contributions, and to each individual file for individual topic writing,
editing, and translation. The guide-wide file is published as part of the guide
(in the appendix).

* Used Drupal.org issues and commit authorship to give credit to people who
contributed to the project.


[[notes-project-repo]]
==== Project, revision control, and development site

We thought for a while that due to Drupal.org Git repository policies, we might
not be able to host this project on Drupal.org (due to license
incompatibility). But luckily, this issue was resolved and we were able to use a
Drupal.org project with a Drupal.org git repository.

Since we had standardized on AsciiDoc for formatting, we needed to be able to
build the output from source and display it on a site, keeping it updated as we
went. Since this involves installing software on a server, our immediate
"solution" was for Jennifer to do the builds locally, and upload them to a
Drupal.org development site. This was obviously not sustainable, but after a
short delay, we were able to have the Drupal.org infrastructure team set up a
"Jenkins" job that updated the source and build output whenever a commit was
made to the Git repository.


[[notes-file-structure]]
==== Structure of files in the Guide

We decided to put the source files to the Guide in directories by language, such
as source/en, source/es, etc. This way, all the files for one branch were
together and could be built together into the desired output.

We put all of the source files into one flat directory, with an images
subdirectory. Because there were a lot of files, we used a prefix naming system,
such as naming all the topics related to blocks _block-something.txt_. We made
also made sure that the file name matched the AsciiDoc ID of each topic. This
scheme wasn't all that great, however, because as we started working on the
topics, we realized that some of them needed to be moved to different sections,
and by then it was too late to change the IDs and hence file names easily. We
could have gone back at the end and fixed names and IDs, but didn't choose to do
that.

Also, on the suggestion of one of our participants the first day, we adopted a
naming convention for images that they should be named with a prefix of the text
file name they are included in. This was a good idea, as it helped to organize
the images directory.


[[notes-tracking]]
==== Tracking and making progress

We decided that unlike in some projects, we didn't want to insist that every
topic submitted by the original writer (for instance) was free of typographical
errors. Instead, we used a multi-phase approach, where the different phases of
writing and editing could be done by different people and added to the
repository in each stage as the topic was refined. Types of editing: copy
editing, testing for correctness, and adherence to the guidelines.

We decided to use a Drupal.org issue for each phase of writing and each editing
task, so that we would have a place for people to upload their files, and for
the project managers to provide feedback at each stage. But Drupal.org issues
are not a great way to track overall status of a project, so we
used a spreadsheet, where each topic was a row, and there were columns for the
topic information (title, file name, what it covers), as well as the who/status
information for each task. Some tasks were across many topics, so those were put
on a separate tab of the spreadsheet.

We found early on that it was much better for project managers to create the
issues than to expect contributors to create them. Contributors were also asked
to "follow" their issues and sign up for email notifications, but even so, some
contributors were unresponsive.


[[notes-contributor-guide]]
==== Contributor guide, outline, and templates

Before we launched the general volunteers' work on this project, the content
coordinators wrote a contributor guide and made templates for the topics. Then
we made a topic outline. We felt that this was good for the coordinators to do
rather than letting the participants suggest topics (we needed to keep the
outline limited and focused on the goals of the book).

We actually started getting topics written before we had finalized the outline:
we picked out a few sets of related topics that we were certain would be in the
book, and opened those up for editing. This seemed to be fine. We maintained a
list (in a separate tab of the Tracking spreadsheet) of all of the topic
suggestions and our decisions as to what should be done about them, and them
moved topics to the Decided tab (the tracking tab) when we decided they should
be worked on.

We had a development site where people could view and edit the files in the
Guide (as well as the Guidelines). In order to build that site, for each topic
we wanted to open up to editing, we had to copy the appropriate template (we had
different templates for Task and Concept topics) to the file name we wanted it
to have, add that to the main Outline file, and then compile the project using
the AsciiDoc tools. This meant that at a minimum, we had to fix the topic ID in
the template file, because AsciiDoc complains if there are duplicate IDs for
topics (and the template explained you needed an ID for each topic).

Lessons learned:

* Giving people the templates in individual files was a good idea, so that we
chose the topics that were ready to work on, and their file names. It made some
extra work for the coordinators, but was good for the participants.

* When we copied the templates into their final file names, we discovered that
it would have been better to put something recognizable for the topic titles
into the templates (instead of the generic ones in the template files). So,
after a while we switched to doing this. People
using the on-line editor otherwise couldn't find the files they were supposed
to be editing, and that meant that sometimes they picked the wrong file (with
perhaps the wrong template) to edit. We eventually wrote a script that would
create a batch of template files.

* The guidelines were initially very long, and people didn't easily see how to
get started. To remedy that, we posted a quick start list initially on the
project home page, and eventually this was moved into the contributor guide so
that everything was in the same place. This proved to be much easier to follow.

* The first few participants made a lot of the same mistakes. So, we updated the
templates and instructions so that the correct way of doing things would be
explained there.


[[notes-communication]]
==== Communication

The following communication channels were used:

* Posting major announcements on groups.drupal.org/documentation -- works pretty
well.

* Tweeting when we do so from @drupaldocs -- not sure if people see this but it
cannot really hurt.

* We set up an email list for participants, but aside from us posting
announcements, this didn't get traffic. We were hoping people would discuss how
it was going or ask for help, but they didn't.

* The tracking spreadsheet was open to the public to view. We decided we didn't
want to let everyone edit it. It seemed better to let people use issues to
communicate claiming tasks and their progress, and leave the spreadsheet updates
to the project managers.

* We had meetings in IRC for a while. We considered Hangouts but were not sure
that would work well with large numbers of people; on the other hand, IRC may be
unfamiliar to some people too. Not too many people attended the meetings, and we
eventually stopped having them.


*Attributions*

Written/edited by
https://www.drupal.org/u/jhodgdon[Jennifer Hodgdon] and
https://www.drupal.org/u/eojthebrave[Joe Shindelar].
