Advertising sustains the DA. Ads are hidden for members. Join today

On this page

3.2. Issue templates and checklists for each phase

Last updated on
11 January 2024

On this page:

3.2.1. 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:

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.

3.2.2. 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 Section 3.2.4, “Issue templates and checklists for editing”, with issue title "Guidelines edit: …") to get another volunteer to make updates, or do the edits directly and commit the changes.

Guidelines checklist:

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.

3.2.3. 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.

3.2.4. Issue templates and checklists for editing

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

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:

  1. 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:".

  2. Editing the entire User Guide 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]

  3. 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 Section 2.5, “Style Guide for the Editing Phase”, Section 2.4, “Style Guide for the Writing Phase”, and current output of the guide 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").

3.2.5. 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:

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 Jennifer Hodgdon and Joe Shindelar.

 

This page is generated from AsciiDoc source from the User Guide. To propose a change, edit the source and attach the file to a new issue in the User Guide project.

Source file: phase-checklists.asciidoc

Help improve this page

Page status: No known problems

You can: