3.1. Managing the project

When committing changes from contributors (writers and editors) to the guide:

When starting a new project, it is a good idea for the project coordinators to define the outline ahead of time. The outline consists of a list of topics, organized into chapters, and you’ll need to define the name of each topic, its file name, what each topic should cover, and the ordering and organization into chapters.

Another aspect of the plan, if it is some type of user guide material, is to come up with a guiding scenario, which provides a unified context for all of the topics. As an example, in the User Guide project, we selected the scenario of creating a web site for a farmers market, and we made sure that whenever examples were called for in topics, they were related to this scenario. You’ll also need to create (or find) sample text and images related to the scenario, which authors of topics can use in their writing and screenshots. Make sure the sample images have compatible licenses. A good place to search for images (you’ll still have to check the licenses) is Wikimedia Commons.

Ideally, each topic in this guide should be reusable (assuming that another project uses the same guiding scenario, anyway). To facilitate that:

Once you’ve defined what the outline and scenario should be, follow these instructions to set up the project and instructions pages (some of the instructions assume this setup and directory structure). Note that you can also start the process with just a few topics, and then add to the outline as you decide on more of it (see Section 3.1.3, “Adding new topics”). Here are the suggested steps for initiating a project:

If you need to add a new topic after the project is already started:

There is a Perl script in the scripts directory of the User Guide project called mktopics.pl that will make a batch of topic files. It has instructions at the top.

For each phase, follow these steps:

Each language the User Guide will be translated into will need a team, which should normally be formed from the existing translation team for the software. As a prerequisite, the translation team should have already translated a large portion of the terms in the software user interface into their language. Then, the team should choose a manager or managers for the User Guide translation project, and form a group specifically targeted at translating the User Guide.

Once the new team has been established, the overall project managers and language team manager(s) will need to follow a number of steps to initiate a new translation. To do this, start by making an issue to track translation set-up, and another one to track screenshot making (templates below). Then follow the steps in the issue templates (creating the second issue is one of the steps in the first issue).

In these issue templates, make the following replacements:

Here is the template for the "setup" issue:

This issue is to track progress on setting up for translations into LANGUAGE.

Tasks:

<ol>

<li>Add a new issue component for translations into this new language, by editing the Project page. The component should be called "LANGCODE translation".</li>

<li>Make a new source/langcode directory. Copy all of the source (English) files, including the images subdirectory, into the new directory. Keep the file names and IDs the same as they were in English.</li>

<li>Add a new section to the attributions.txt file for the translation team management for this language. Template:
<code>
==== Translation into LANGUAGE_NAME

The LANGUAGE_NAME translation of this guide was coordinated by:

* https://www.drupal.org/u/person1[Person One]

* https://www.drupal.org/u/person2[Person Two] of http://example.com[Company]
</code>
</li>

<li>Make a separate issue for the screenshots. See Guidelines document for issue template.</li>

<li>Grant issue maintainer and VCS commit permissions to the manager or managers of the language team for the new language, by editing the Maintainers page for the project. <strong>Note: Language team managers will need to re-clone their Git repositories using "Maintainer" mode after receiving this permission, in order to be able to commit to the repository.</strong></li>

<li>Make issues for translating each topic into the target language. There is a spreadsheet file scripts/bookmarks.fods that will aid in doing this. You will need to translate the guide-docinfo.xml file, as well as all of the .txt files in the source directory.</li>

<li>At least one leader of the translation group needs to subscribe to the email list the project uses for notifications about updates to the English source that require translations to be updated. This is at: [EMAIL_LIST] </li>

<li>Copy the English configuration file scripts/lang-en.conf to file name lang-lc.conf, where lc is the language code. Optionally, check https://github.com/asciidoc/asciidoc to see if there is an existing language configuration file for that language, and copy the three lines we need in our language configuration file from there, so that they are translated already.</li>

<li>Add notes to the guide.txt and glossary.txt file translation issues, that when the chapter headers for the Preface, Index, and Glossary sections are translated, the lang-lc.conf file translations of these same words need to be done at the same time. Suggested note:
<code>
When this translation is done, make sure to update the scripts/lang-lc.conf (for your language code) at the same time so the chapter headings for Preface, Index, and Glossary in that file match what is in the source file for this issue.
</code>
However, if you found an existing lang-lc.conf file on Github, you should instead edit the guide.txt and glossary.txt files so that these headings match the translations you put in.
</li>

<li>Add langcode to the build scripts in scripts/languages.txt, and verify that it builds without errors. You may need to adjust the font used for PDF files in the scripts/mkebooks.sh file.</li>

<li>Decide whether your team wants to use translation memory software or not. You can read more about this in the Translation Memory section of the <a href="PM_GUIDE_URL">User Guide Contributor Guidelines - Project Management page</a>.</li>

<li>Optional but recommended steps:
  <ul>
  <li>Make a translation glossary for this language. File scripts/TermsToTranslate.fods is a good starting point. This should be located in a place that the language team normally uses for communication, such as on localize.drupal.org.</li>
  <li>Create an issue to track translation progress. It should list the individual translation issues, providing a place to look to see which are done and which still need to be done. You can make a list of the issues in the issue summary by following these steps:
  <ol>
  <li>Open the Issues page for the project.</li>
  <li>Filter to the issue component for your translation. You'll see the first page of issues.</li>
  <li>Open a JavaScript console tool in your browser (usually by using the Inspect or Inspect Element context menu).</li>
  <li>Execute this JavaScript code to make a list of the issue numbers shown on this page:
<code>
jQuery("tbody .views-field-title a").each(
  function(){
    console.log("[#" + jQuery(this).attr("href").replace("/node/", "") + "]");
      }
);
</code>
  </li>
  <li>Copy and paste the output into the issue summary.</li>
  <li>Go to the next page of issues and repeat the JavaScript, until all issues have been found.</li>
  </ol>
  </li>
  </ul>
</li>
<li>Start translating!</li>

</ol>

Here is the template for the "screenshots" issue:

This issue is for tracking progress and problems with the LANGUAGE screenshots.

Tasks and their status (unmarked tasks are assumed not to be done yet):
<ol>

<li>Ensure that most of the current version's user interface has been translated into LANGUAGE, so that the screenshots will show very little if any English on them.</li>

<li>Translate the "scenario text" into LANGUAGE. The text to be translated is the "Scenario Text" section of the scripts/TermsToTranslate.fods spreadsheet. What is needed is a 3-column sheet with these columns:

<ul>
<li>Context (the column called Context in the TermsTo Translate sheet)</li>
<li>English text</li>
<li>Your language text</li>
</ul>

</li>
<li>Make initial automated screenshots. Procedure: See User Guide Tests module (https://www.drupal.org/project/user_guide_tests)</li>
<li>Make initial non-automated screenshots. See the source/en/images/README.txt file for details of which images need to be made.</li>
<li>Check each screenshot to make sure it is all in the target language and is readable. The LANGUAGE language team will do this as they translate each topic. If problems are found, add tasks here so that the screenshots can be updated. Leave this issue open until all the topics have been translated and the screenshots checked and/or updated.</li>
</ol>

Some language translation groups have found that using Translation Memory (often abbreviated as TM) software helps them keep their translations consistent and save time. This section explains what a TM is, and describes how to set it up.

From time to time, there will be reasons to make updates to the User Guide. For instance, it may need to be updated if a new version of Drupal comes out, if readers have reported problems, or if new topics need to be added.

If the text has been translated, updates are complicated somewhat, because translators need to be notified about the update. This section tells how to go about making updates, ensuring that translations are also updated if needed.

Attributions

Written/edited by Jennifer Hodgdon, Joe Shindelar, and Balu Ertl of Brainsum.