Documentation writing regulations

上一篇 / 下一篇  2016-07-05 15:39:10 / 个人分类:Testing

Document structure

. Use this section to check the general format when creating a new document.

. Some basic rules and examples to ensure the high quality of documents.

  • Review process

. Document reviewing process within team.

  • Templates

. A reviewed version of template for common type of documents.

  • Most frequent mistakes

. Use this section to record all the "popular" mistakes we make to document and use them as a reminder.

Document Structure

You can tick the box in the front of each check item to ensure the request is checked and satisfied.

  • Document title

    1. Create meaningful document titles, which are accurate, consistent, and reflect the scope of the document. A meaningful title should contain following identification components:

Identification components , Product name, Product release identifier, Sub-product name, Content type, Additional information

2. Parallel structures make text easier to read and follow and use same verb form.

Examples

DO

: Troubleshooting RNC and Upgrading RNC

NOT:

Troubleshooting RNC and Upgrade RNC

3. Capitalize the first letter of a word, except it is a  conjuction or preposition.

  • Table of contents

  1. Use a separate page for table of contents or at least separate the table of contents and main boby.
  • Ensure that all headings flow in logical order. Update the table of contents after updating the document each time.

  • Change history

It's recommended to have a change history for each document, recording the changes for each revision and responsible person. A recommended table format is:

Issue, Date, Handled by, Summary of changes

  • Contents

Usually the contents is the main body of the document. Make sure all the essential parts are included and logically organized. If writing a step by step instruction, make sure the steps are in right order. Refer to Writing

section for more regulations about contents.

It's recommended to have summary in the beginning of each chapter to describe:

  • Trouble shooting

Trouble shooting includes solutions for problems customer may meet ,while operating the instructions written in the document. This part is optional.

  • Appendix

An appendix should be inserted at the end of a document for supplementary informationthat which is not an essential part of the text but might be useful to the reader. Regulations:

  1. Usually an appendix is included in a document with an unnumbered heading and numbering restart.
  • Using "Appendix" to seperate main body and appendix.
  • All appendix content should be referenced in main body.
  • Headers and footers

Keep the headers and footers identical with the document title/company name/date.

  • Document name

Keep the document name identical with the document heading.

Writing

  • Creating headings

Headings describe the content of a section or subsection. Create headings that are concise, clear, accurate, consistent, and easy to understand at first glance. Regulations:

  1. Capitalize just the first letter of the heading and proper names or abbreviations.
  • Use the -ing form. of verbs in headings for chapters.
  • Headings should be parallel in structure. For example, use the same verb form. for headings on the same level.

Examples

DO

: Acknowledging alarms

NOT:

Using the acknowledgement function with alarms

  • When creating headings, use proper level of headings, so that the table of content can be generated/updated properly. Do not create more than four

levels of headings.

  • Avoid starting a heading with an article, or with a technical term or product name that begins with a lower-case letter, such as gsmSCF.

  • Writing procedures

  1. When writing procedures, include only one task per step.
  • Ideally, procedures should be between three and nine steps.
  • Graphics can be used to illustrate the task, however, only use graphics that are important to the procedure (for example, do not include confirmation dialogs).

  • Using the imperative form. and the second person; Avoiding the third person and passive. 

Examples

DO

: Save this file before proceeding.

NOT:

The user must save this file before proceeding.

NOT:

This file must be saved before proceeding.

  • Do not use the word please

in technical documentation.

  • Use the present tense. Avoid the future tense (will or shall).

Examples

DO

: The screen changes when you click OK.

NOT:

The screen will change when you click the OK.

  • Whenever possible, use positive constructions to give information.

Examples

DO

: To enable the Select and Close button, select the correct trail type.

NOT:

The Select and Close button is not enabled unless you select the correct trail type.

If something must be avoided, use a negative command in imperative form.

  • Creating sentences

  1. Include only one main idea per sentence. If expressing two or more ideas per sentence, insert parenthetical remarks and conjunctions between each idea.
  • When writing instructions, always use the active voice. This is because passive sentences do not clearly indicate if the system or the reader must perform. a task.
  • Punctuate every complete grammatical sentence with a final period (full stop).
  • Links

Links should be used to guide the user to correct information.Do not use links/cross-references if the additional information is brief. In such a case, it is better to repeat the information.

  1. Keep usability and reusability in mind when linking.
  • Distinguish links to another destination outside the topic. Make it clear to the user if they are headed to another document.

  • Whenever possible, place the link at the end of a sentence.
  • When creating links for on-screen documentation, do not use numbers to refer to chapters, figures, and so on. Always use the relevant caption, heading, or title as the linking text, preceded by see

.

Examples

DO

: For more information, see Verifying CA certificates.

NOT: 

Refer to Chapter 3 for more information.

  • Grammar guidelines

  1. Use standard American English as the convention for all spelling, grammar, and punctuation.
  • Using simple words: When choosing between two words that mean the same thing, select the word that is most commonly used.
  • Spell and capitalize registered product names in the same way as the manufacturer.

Examples

• Microsoft PowerPoint

• UNIX operating system

• DX 200 Centrex

  • Usage of terms and abbreviations
    • Provide an explanation or a link to an explanation for each abbreviation and acronym in at least the following contexts:

  • when the abbreviation first appears in a text, such as a module

  • if the abbreviation occurs again so much later in a text that the reader has probably forgotten its meaning

  • in the glossary(or terms and abbreviations chapter)

Review Process

Review is mandatory for document types, including but not limited to: installation instructions, configuration instructions, test reports and release notes.

It is recommended to have email review before meeting review, to ensure all the team members have read the document before meeting and keep the meeting efficiency.

Email Review

Documents should meet following criteria before author sending out for review:

  • No basic spelling and grammar issue in the document.
  • Documents saved in Sharenet. Do not attach document in email review invitation.

There are 2 types of reviewers:

Mandatory

reviewer: Someone working in the same area, except the author.

Optional

reviewer: All other team members

For document Reviews using e-mail  the following templates should be used:

  • Template for Review Invitation

- E-mail template for review invitation. 

  • Template for Review Minutes

- Excel template for review invitation, comments and report. The review minutes file should be saved under the same folder in SVN together with the reviewed document, named as _review_minutes.

For e-mail reviews, the following rules apply:

  • All names in the "TO" are considered MANDATORY

reviewers. First name in the "TO" list is also the APPROVER. Mailing lists can not be used in the "TO", only in "CC".

  • All names or mailing lists in "CC" are considered OPTIONAL reviewers.
  • Author must ensure that all mandatory reviewers (or respective deputies) are notified about the review request.
  • All mandatory reviewers must reply to the review request before review deadline (otherwise they should not have been considered mandatory "TO" but Optional instead "CC").
  • If there is no meeting review followed up, the author must close the review and summarize the comments after receiving feedback from all mandatory reviewers. The review minutes

should be sent to all reviewers. If there is meeting review later, the review minutes should be sent after the meeting.

  • For E-mail offline Reviews: Subject should start by "E-MAIL REVIEW

". In the message body, please fill the "Program" field with "Node Manager Server" followed by the remaining part of program name.

Meeting Review

Meeting review should be held after sufficient email review, if needed. The participants should include: mandatory reviews and some of the optional reviewers. Arthor should ensure all the participants presence, otherwise the meeting should be cancelled.

Purpose of review by meeting:

  • Going through all comments provided by reviewers in email review phase and collecting new comments.
  • Analysis and decision on each comment.
  • Creation of review minutes (including all comments and responses to comments). Review minutes are mandatory for documents for which a review is required.

Roles

  • Author (A)
  • Reviewer (R)
  • Manager (Mgr)

Inputs

Key activities

Outputs

  • Review comments
  • Verify that all mandatory reviewers are present or have provided comments (A)
  • Record comments received during meeting(A)
  • Evaluate single comments (approved/rejected/duplicate) (A+R)
  • Decision if re-review is necessary (A+R)
  • Possible escalation if needed to Manager, by default one level above the author (A, Mgr, R)
  • Review minutes (A) The review minutes file should be saved under the same folder in SVN together with the reviewed document, named as _review_minutes.
  • A: Response to reviewers’ comments (i.e. accepted/rejected/duplicate)

TAG: writing

 

评分:0

我来说两句

我的栏目

日历

« 2021-11-09  
 123456
78910111213
14151617181920
21222324252627
282930    

数据统计

  • 访问量: 1904
  • 日志数: 4
  • 书签数: 1
  • 建立时间: 2011-07-16
  • 更新时间: 2016-07-05

RSS订阅

Open Toolbar