[[phase-checklists]]
=== Issue templates and checklists for each phase

[role="summary"]
Issue templates project managers can use for each phase of the project. Also,
checklists for committing changes in each phase.

On this page:

* <<phase-checklists-writing>>
* <<phase-checklists-guidelines>>
* <<phase-checklists-testing>>
* <<phase-checklists-copyedit-task>>
* <<phase-checklists-translating>>


[[phase-checklists-writing]]
==== Issue template and checklist for initial writing

Use the following issue summary template for issues for writing individual
topics. You'll need to replace the following:

* Before you start making issues, put in the URL for <<copyright-license>> where
it says [COPYRIGHT-LINK] and the URL for <<practicalities-writing-phase>> where
it says [QUICK-START-LINK].

* For each issue, the things like [TOPIC TITLE] need to be replaced with actual
information for the topic.

* The issue title should be something like: "Write filename.txt".

Here is the issue summary template for writing issues:
----
<h3>Task for this issue</h3>

Write the following topic.

<strong>Title:</strong>  [TOPIC TITLE]
<strong>Section:</strong> [BOOK SECTION NAME]
<strong>File name:</strong> [FILE NAME]
<strong>Covers:</strong> [COPY THE Covers INFO FROM THE TRACKING SPREADSHEET]

<h3>Instructions</h3>

See [QUICK-START-LINK]

<h3>Checklist for this task</h3>
- Does it follow the template?
- Have the comments and placeholder text been removed from the template?
- If sections of the template are not needed, are they still there but turned into comments?
- Is everything the topic was supposed to cover included, and nothing extra?
- If there are @todo notes, are they clear?
- If there are images included, do they include instructions for how to redo them in a comment? (Note: Screenshots do not need to be perfect. Just make a rough cut.)
- Is attribution provided? See [COPYRIGHT-LINK]
----

Writing phase checklist for committing:

* Does it follow the template?

* Have the comments and placeholder text been removed from the template?

* If sections of the template are not needed, are they still there but turned
into comments?

* Is everything the topic was supposed to cover included, and nothing extra?

* If there are @todo notes, are they clear?

* If there are images included, do they include instructions for how to redo
them in a comment? (Note: Screenshots do not need to be perfect. Just make a
rough cut.)

* Is attribution provided? You will need to add the attributions statement to
the bottom of the file before committing it.


[[phase-checklists-guidelines]]
==== Checklists for guidelines and formatting

After making a commit for the writing phase, the committing project manager
should check for adherence to the following guidelines (rather than requiring
that the writer has followed them). If there are problems, the committer can
either file an issue (using the template in <<phase-checklists-copyedit-task>>,
with issue title "Guidelines edit: ...") to get another volunteer to make
updates, or do the edits directly and commit the changes.

Guidelines checklist:

* Does it follow our guidelines for good writing? See <<good-writing>>.

* Does it speak to the intended audience?

* Does it follow the scenario and use the provided text/image assets? See <<follow-scenario>>.

* Does it have appropriate index entries?

* Is the navigation described in the standard way? See <<text-navigation>>.

Next, rebuild the guide (or wait for the automatic build to happen) and check
the output, as well as the source file, for formatting. Check for formatting
issues, and fix them with a commit (this is recommended, rather than filing an
issue and asking for a volunteer to fix the problems).

Formatting checklist:

* The formatting of the headers, subheaders, lists, etc. works (no wrong
numbers, etc.).

* Images do not spill out of margins; narrow images are not artificially widened
(you may need to take out or add +,width="100%"+ in image tags).

* Images are named appropriately. For source file _my-filename.txt_, the file
name should be _my-filename-short-description.png_.

* Text should be wrapped in lines going out to around 80-characters, without
going over, as much as possible. However, lines specifying images, links,
and the like can go over 80 characters to keep the image/link, including
attributes, all together on one line.

* When formatting a bullet list or numbered list, within each list item,
subsequent lines should start at the left margin. Paragraph breaks within a
list item are generated by + signs. Example:

----
. This is a numbered list item. After reaching the 80 character
line length, the next line starts at the left margin.
+
And this is a second paragraph within the same list item.
----

* All of the sections from the appropriate template should be present in both
Task and Concept topics. If they are empty, they should be commented out:

----
// ==== Site prerequisites
----

* Within a particular section, such as Steps, if a sub-heading is needed, it
uses ===== notation rather than just being a sentence in bold or some ad-hoc
formatting like that.

* We don't need a heading at the top of Steps that just repeats the Goal. Just
remove it.

* Bullet lists should never have just one item. Take out the bullet if so and
make it a normal paragraph.


[[phase-checklists-testing]]
==== Checklist for testing

Here is a checklist for what testers could look for in testing sessions (you
might post this list somewhere or hand out copies):

* Do the concept topics make sense?

* Is terminology defined the first time it is used?

* Are concepts introduced in Concept topics (not in Task topics)?

* Are the steps in Task topics clear and concrete, and do they work if you
follow the steps exactly as written?

* Are the instructions in the steps presented fully in the text (with tables for
filling out forms)?

* Are screen shots provided at appropriate times (not too many or too few), to
supplement and illustrate the text?

* Does the user interface text mentioned in the steps match what you see in the
actual user interface?

* Does the navigation get you to the desired page, and is the final URL
specified in the navigation text correct?

* Are the knowledge and site prerequisites listed for each topic adequate?

Assuming that the testing phase is happening before copy editing and screenshot
improvements, you might want to tell the testers to _not_ look for or report
the following types of problems:

* Typographical, spelling, grammar, and punctuation errors, unless they have
made the text incorrect or prevented understanding it.

* Whether screen shots exactly match the text, instructions, and what you see in
the user interface.


[[phase-checklists-copyedit-task]]
==== Issue templates and checklists for editing

Use the following issue summary template for issues for copy editing. You'll
need to replace the following:

* Put in the URL for <<copyright-license>> where it says [COPYRIGHT-LINK], and
the URL for <<practicalities-editing-by-task>> where it says [QUICK-START-LINK].

* For the task area and issue title, see list of suggestions below the
template.

Issue summary template:

----
<h3>Task for this issue</h3>

[SPECIFIC TASK]

<h3>Instructions</h3>

See [QUICK-START-LINK]  -- but skip the section on finding a task to do, since you have selected this one.

<h3>Checklist for this task</h3>
- Is a patch file provided? If only one or a few topics were edited, you can instead attach the updated source file(s).
- Is the edit complete and correct?
- Is the work free from additional edits outside the scope of the provided guidelines or task?
- Is attribution provided? See [COPYRIGHT-LINK]
----

This template can be used for the following:

. *Editing for content after testing*. In this case, put specific editing tasks
in the task section, which will resolve the problems uncovered during
testing. The issue title should start with "Content edit:".

. *Editing the entire project_name for one guideline*; for example, the
guideline could be:
+
In the text of the guide, use "website" instead of "web site".
+
Here is the template for the Task section of the issue summary; you will need to
substitute the name of the project, such as User Guide, where it says
[PROJECT-NAME], and the guideline where it says [GUIDELINE HERE]:
+
----
Copy edit the entire [PROJECT-NAME] to adhere to the following guidelines:

[GUIDELINE HERE]
----

. *Editing one topic so that it complies with all of the editing
guidelines*. For this type of issue, use the following template for the task
section. You'll need to put the topic information near the top, and you'll need
to substitute in the URLs for <<guidelines-editing>>, <<guidelines-writing>>,
and project_current_output for [EDITING_GUIDELINES], [WRITING_GUIDELINES], and
[PROJECT_OUTPUT]. Make the issue title start with "Copy edit:".
+
Here is the template for the Task section of the issue summary:
+
----
Copy edit the following topic:

<strong>Title:</strong>  [TOPIC TITLE]
<strong>Section:</strong> [BOOK SECTION NAME]
<strong>File name:</strong> [FILE NAME]

Look for:
- Typographical errors
- Spelling errors
- Punctuation errors
- Grammar, writing style, and usage problems
- Adherence to the project's editing guidelines: [EDITING_GUIDELINES]
- Adherence to the project's writing guidelines: [WRITING_GUIDELINES]
- Formatting problems in the output. The output can be found on: [PROJECT_OUTPUT]
- Also note (but do not fix) problems with screen shots in the output.

Note that the "single-issue" guidelines in the Editing guidelines page, as well
as the entire Writing guidelines page, should have already been enforced. But it is still a good idea to at least check them quickly.
----

Editing phase checklist for committing:

* Is a patch file provided? If only one or a few topics were edited, you can
accept updated source file(s) instead of a patch.

* Is the edit complete and correct?

* Is the work free from additional edits outside the scope of the provided
guidelines or task?

* Is attribution provided? You will need to add attribution information to
either the bottom of the file(s) that were edited (if there were major edits to
this file), or to the section of the guide-wide _attributions.txt_ file (in the
case of minor edits to the file(s) that were edited, we instead give credit to
the person as a "guide-wide editor").


[[phase-checklists-translating]]
==== Issue templates and checklists for translating

Use the following issue summary template for issues for translating individual
topics into a specific language. You'll need to replace the following:

* [LANGUAGE] with the full name of the language (for example: Spanish).

* Before you start making issues, put in the URL for <<copyright-license>> where
it says [COPYRIGHT-LINK] and the URL for <<practicalities-translating>> where
it says [QUICK-START-LINK].

* For each issue, the things like [TOPIC TITLE] need to be replaced with actual
information for the topic.

The issue title should be something like: "[LC] Translate filename.txt"
(replacing LC with a two-letter code like "ES"). Put the issue into the issue
component that was set up for translating the guide into this language.

Here is the issue summary template for translating issues:
----
<h3>Task for this issue</h3>

Translate the following topic into [LANGUAGE]:

<strong>Title:</strong>  [TOPIC TITLE]
<strong>Section:</strong> [BOOK SECTION NAME]
<strong>File name:</strong> [FILE NAME]

<h3>Instructions</h3>

See [QUICK-START-LINK]

<h3>Checklist for this task</h3>
- Is a topic file or patch file uploaded?
- Is the translation complete?
- Did you check over the images and note any problems, or note that they are fine?
- Did you follow the glossary for your language?
- Are the AsciiDoc formatting, image file names, and cross-link IDs left as they were in the original English text?
- Is attribution provided? See [COPYRIGHT-LINK]
----

Translation phase checklist for committing:

* Is this issue for your language? You should only review issues and make
commits for your own language.

* Is a topic file or patch file uploaded, and is the file that is edited or
provided in the correct language subdirectory?

* Is the translation complete?

* Has the translation been reviewed?

* Were the images reviewed? File a separate issue if a screenshot image needs to
be fixed.

* Was the glossary followed?

* Are the AsciiDoc formatting, image file names, and cross-link IDs left as they
were in the original English text?

* Is attribution provided? You will need to add attributions for the translator
and reviewer to the bottom of the file. Note that the attributions for the
glossary are located in the main _attributions.txt_ file and cannot be added to
the _glossary.txt_ file.


*Attributions*

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