Reviewing Technical Documentation February 06 - 09, 2007. - презентация

1 Reviewing Technical Documentation February , 2007

2 Introduction Basic Validation Process AT Validation Process Goals Technical Writers Checklist Reviewers Checklist Reviewing Technical Documentation

3 Reviewing Technical Documentation – Introduction About the role of documentation Technical documentation is what gives support and credibility to a product. There are several indicators for assessing quality documentation: - Accuracy Credibility is weakened by inaccurate content, typographical errors, misspelled words, incorrect grammar, and inconsistencies in style. - Clarity Clarity is obtained by logically structuring content and eliminating any information which has no added-value. - Added value Knowing the product you are writing about, and understanding financial concepts are paramount in adding value to documentation. Writing is not just about describing, it's about explaining. A thorough review process is essential to developing an accurate and useful documentation, compliant with all quality indicators.

4 Reviewing Technical Documentation – Introduction (suite) What is a document review? Reviewing a technical document consists in checking the entire content by different reviewers. A document review focuses on: - the accuracy, clarity, conciseness and completeness of the technical content, as well as - the grammar, terminological consistency, and formatting of the document.

5 Reviewing Technical Documentation – Basic Validation Process The first review cycle takes place within the documentation team. Cycle I - cross-check by another technical writer - peer review by the lead technical writer - peer review by the project leader This cycle is followed by a functional review cycle. Cycle II - developer review - product manager review The result of both review cycles allows the document to be corrected and finally validated.

6 Reviewing Technical Documentation – Basic Validation Process Cycle I Doc team Technical Writer 2 Project Leader Lead Technical Writer product managers AT financial engineer AT English Mother Tongue Reviewer developers Cycle II - Functional Review Technical Writer validation

7 Review Technical Documentation – AT Validation Process In addition to standard Cycle I reviewers, Allied Testing requires two extra reviewers focussing on the linguistic and financial aspects of the documentation: - an English native speaker checking for grammatical correctness - a financial engineer checking the accuracy of the financial terminology, concepts and formulas

8 Reviewing Technical Documentation – Goals The different reviewers involved in the validation cycle focus on all quality aspects. Peer writers check: - the consistency of formatting, text, and terminology - adherence to style standards and technical writing conventions - clarity of procedures and examples Lead writers check that: - the vocabulary, style, and content of the documentation targets the right audience - information is pertinent and cross-referenced where necessary - product features and functionalities are fully described in the documentation - text, examples, and screenshots are up to date, useful and technically correct

9 Reviewing Technical Documentation – Goals Project leaders check: -the document correctly satisfies the specifications and requirements -identify any deviation from style guide standards -suggest areas of improvement to the writer(s) Financial engineers check that the financial terms, concepts and formulas are correct. Developers check that all features are documented accurately and that the business logic and workflow are correct. Product managers -critical product information receives proper emphasis -the documentation reflects the business objective of the product

10 Technical Writers Checklist The first step to writing a good document is to review your draft. Examine every detail from the readers point of view, then rewrite to sharpen, simplify, and clarify. As you rewrite, ask yourself these questions: -Are my ideas logically ordered from the simple to the complex? -Have I written simple, succinct sentences? -Have I eliminated unnecessary words, especially modifiers? -Have I used verbs in the active rather than passive voice? -Have I chosen words that express my meaning precisely? -Have I avoided jargon and clichés? -Have I explained all acronyms? -Have I used correct grammar and punctuation? -Have I proofread for spelling and typographical errors? Do not approve your own content! It should always be validated by someone else.

11 Reviewers Checklist – Overview The following list contains the items that a reviewer is to supposed to check: -Content Coverage -Content Structure and organization -Grammar -Graphics and Examples -Terminology -Writing Style

12 Reviewers Checklist 1. Coverage All features have been documented. Irrelevant topics have been kept out of the documentation.

13 Reviewers Checklist 2. Structure and Organization Style guide lines have been followed. Concepts flow logically, e.g. chronologically, user interface driven, etc. Superfluous or repetitive material is eliminated. Headings are descriptive and concise. Information is easy to find. Information is task-oriented where appropriate. Reference and conceptual information are separated or removed from task descriptions. Critical information receives the appropriate emphasis.

14 Reviewers Checklist 3. Grammar -Punctuation follows editorial and documentation set guidelines. - Capitalization is consistent and follows editorial guidelines. - Spelling is consistent and follows editorial guidelines. - Subjects and verbs, pronouns and antecedents agree. - Articles are used appropriately. - Sentences use grammatically correct structures.

15 Reviewers Checklist 4. Graphics and examples Graphics (diagrams and illustrations) and examples have been used where necessary, and contribute to the understanding. Screenshots are up-to-date.

16 Reviewers Checklist 5. Terminology Terminology is consistent throughout the document and complies with the standards. New terms are defined and appear in a glossary. Abbreviations and acronyms follow editorial guidelines. The glossary is exhaustive. The definitions are clear and correct. Product names are used correctly and consistently.

17 Reviewers Checklist 6. Writing Style Sentences are complete and long sentences are divided for readability. Verb tense is consistent. Standard introductory or procedural information use the same sentence structure. Headings of the same type use the same sentence structure and grammatical construction.

18 Reviewing Documentation - Examples Screenshot/example accuracy 1. For example, MyBond_001. The model displays the new name in orange italics. The user-bond is named MyBond_002, whereas the example used in the procedure is called MyBond_ Displays the strike expressed in the quote currency. Given a EURUSD option with a strike of 1.25, the calculated value in In USD is , which equals 1./1.25 = 4/5. =>Given a EURUSD option with a strike of 1.25, the calculated value in In USD is , which equals 1./1.25 = 0.8.

19 Reviewing Documentation - Examples Grammar/clarity 1. The model uses the base bond as the base for structure of your user- defined bond structure. =>The model uses the structure of the base bond as the structure for the user-defined bond. 2. price variation per basis points in dealt currency. => Displays the price variation per basis points in the quoted currency

20 Reviewing Documentation - Examples Consistency with standards This calculator allows corporate treasures, swap dealers or traders to calculate mark-to-market values for currency and IRS swaps stored in a portfolio. =>This calculator allows you to calculate mark-to-market values for currency and IRS swaps stored in a portfolio.

21 Reviewing Documentation - Examples Added-value Deal ID - the deal id entered when saving the swap deal to a portfolio =>the reference given to the swap in when saving the swap deal to a portfolio. Click the hyperlink to open the swap in the relevant calculator.

22 Reviewing Documentation - Examples Structure In Setup, in DataBase Administration, click and choose the desired portfolio that you want to clean. =>Step1 = Open Setup. Step 2 = Click 1 in DataBase Administration and choose the portfolio you want to clean.

23 Reviewing Documentation - Examples Completeness To delete a deal 1.Open Main. 2.Choose the deal you want to delete. [How exactly do you do that?] 3.Click Delete Selected. [And what happens?] Format Resizing/reordering tables Fonts

24