# Technical writing/Requirements analysis

back to Introduction to Technical Writing
This is a working page for the task of the Fred's TW training course.
Scope of possible requirements (something to begin with):
* Content of the training wiki page:
** Must contain only topics related to TW
** Level of TW (for wide audience, for beginners, or for advanced technical writers)
** Level of details (how deep, how much, what to put and what to link to)
** Structure (levels of headings, subheadings, TOC)
** How to organize pages (by theme), size of one page
** Discussion page (what to write there, how)
* Links to other sites:
** To what sites, how to organize, how to describe
* Images:
** Size, location, format, name conventions
* Access and availability:
** Training wiki must be available to everybody at any time
** Access rights (who can write, who can edit, how)
** How to enter changes (log in, check in, lock, etc.)
* Language issues
** International audience (native and non-native speakers), no jargon, British (?) English, simple words, etc.
** Which style guide to use
* Formating conventions
** What must be bold, italics, etc.
TWFred 06:09, 31 July 2007 (UTC)This is a good start. Looks like we've got some groupings of requirements. So far the groupings seem to be:

## Users of the Product

* <Who the User is>
The course is intended for the people who are interested in TW, mostly for those who want to become a technical writer (or at least think about it) and for technical writers who want to improve their skills. It can be also useful for people whose job is related to TW (project managers who deal with documentation, technical translators, business analyst in IT companies and others).
* <User's Goals>
The main goal of our persona is to find out if TW is a wise career and if so, to learn how to become a technical writer and to gain basic TW knowledge and skills.
* <User's Tasks>
The user of the TW wiki do these tasks:
** reading
** following links to read more
** performing assignments
** participating in online critiques and updates of posted work
** communicating with the instructor (if any)
** posting/printing/saving completed work as a portfolio
* <Subject Matter Experience>
Our persona (Joe) is an expert in English. He is not a technical guru.
* <Other User Characteristics>
Joe is very talkative and friendly (he's an English conversation teacher after all). What about PMs, and Bus. Analysts (BAs)?
* <Attitude to technology>
same issue
* <Education>
same issue
* <Linguistic Skills>
* <Age group>
* <Motivation>
The main persona (Joe) wants to investigate changing careers. Other users (PMs, TWs, and BAs) want to enhance existing careers.

## Content

Topics :
| ID | Description | Priority | Assigned to |
| C 010 | The topics on Grammer shall include Use of Articles Active vs passive Punctuation | . | . |
| C 011 | Each topic must have examples that is related to TW | . | . |
| C 020 | The topics on XML shall include: XML Editors <something about basic XML structure> | . | . |
| C 030 | The topics on documentation project management shall include: SDLC, overview Documentation Lifecycle, overview and general steps: *Initialization * Planning * Requirements analysis * Design and development * Integration and testing * Delivery * Maintenance * CMM * Metrics | . | . |
| C 040 | The topics on tools to use in TW shall include: Microsoft Word - maybe some advanced features that technical writers use Tools for making screen shots and handling graphics CMS | . | . |
| C 060 | The topics on the audience analysis shall include: Personas | . | . |
| C 070 | The topics on structuring information shall include: Information chunks Types of structure | . | . |
Exercises :
| ID | Description | Priority | Assigned to |
| C 050 | Training wiki must contain practical exercises | . | . |
| C 051 | Every user of the training wiki will be able to participate in the exercises | . | . |
| C 052 | Exercises must have explanations of the tasks for the participants and instructions how to perform these tasks | . | . |
Projects :
| ID | Description | Priority | Assigned to |
| C 060 | A user must contribute to the project at least once a week | . | . |
| C 070 | Users contribution must be evaluated by the qualified SME | . | . |

## Language Considerations

| ID | Description | Priority | Assigned to |
| LC 010 | The language of wiki articles will be international English | . | . |
| LC 020 | All wiki articles must be written according to the OSS/BSS Publications Style Guide | . | . |
| LC 021 | The OSS/BSS Publication Style Guide must be uploaded to the wiki | . | . |
| LC 022 | Grammar articles must have links to: OSS/BSS Publication Style Guide Chicago Manual of Style Microsoft Manual of Style for Technical Publications | . | . |
| LC 030 | Wiki must enable spell checking errors | . | . |

## Structure and Formatting

Table of Contents :
| ID | Description | Priority | Assigned to |
| SF 010 | The table of contents for each page must not contain more than nine heading 1 sections for ease of viewing | . | . |
| SF 011 | The table of contents must be viewable at the top of every section page | . | . |
Discussion Page :
| ID | Description | Priority | Assigned to |
| SF 020 | Discussion page must be available for each resouce page | . | . |
| SF 021 | Each entry in the discussion page must start with a name of the contributor | . | . |
| SF022 | Questions and comments must first be raised in the discussion page, and then the main article will be amended | . | . |
Formatting :
| ID | Description | Priority | Assigned to |
| SF 030 | Formatting must be consistent for the whole page | . | . |
| SF 031 | Blank lines must divide paragraphs of the text | . | . |
| SF 032 | The format of all lists of items must be consistent bullet list for items, their order is not important numbered list if the order of items is important | . | . |
Tables :
| ID | Description | Priority | Assigned to |
| SF 045 | Tables that extend across pages shall have their headings repeated at the top of the new page <Shall we have such tables? I think it's better to have a table on one wiki page. It's not a book, it's a wiki. Tanya.> | |
Pages :
| ID | Description | Priority | Assigned to |
| SF 040 | Pages must be organized according to the theme (each theme must be on a separate page) | . | . |
| SF 041 | Pages must be linked together with the links: return to<or previous?>:link to the previous page continue to<or next?>: link to the next page Back to Technical Writing: link to the main page of the TW course up: link to the level of the main theme <first level heading???> this page belongs to. | . | . |
| SF 042 | how big must be the page As we feel our persona could be able to read or digest. May be A4 sheet size?? | . | . |
Pictures :
| ID | Description | Priority | Assigned to |
| SF 050 | The images used on the site must be wholly viewable on screen resolutions equal and above 1024x768 | . | . |
| SF 051 | The images must be right-aligned | . | . |
| SF 052 | After double-clicking on the image, the image must open in a new window | . | . |
| SF 053 | Images must have frames and captions <any rules for a caption?> | . | . |
| SF 054 | Names of the image files must reflect the content of the files....<any ideas?> | . | . |
| SF 055 | <Size> | . | . |
| SF 056 | Images used in wiki articles must be uploaded on the wikiversity server | . | . |
Navigation :
| ID | Description | Priority | Assigned to |
| SF 060 | Wiki must contain a navigation bar that is visible from each wiki page and is situated on the left pane | . | . |
| SF 061 | The navigation bar must contain all headings of the first level | . | . |
| SF 062 | Items in the navigation bar must be ordered according to the order of the topics in the TW course | . | . |
Order of Topics :
| ID | Description | Priority | Assigned to |
| SF 070 | Topics must be ordered according to the logic of the TW course <What about writing an order here?> | . | . |

## Level of Detail

| ID | Description | Priority | Assigned to |
| LD 010 | Topics of the TW course will be subdivided into three levels: Introductory (basic, Joe Smith's level) Intermediate Advanced | . | . |

## Access

| ID | Description | Priority | Assigned to |
| A 010 | Training wiki pages must be available on the Internet | . | . |
| A 020 | Users, who want to contribute, must have their own accounts and be logged in, so their contributions could be tracked | . | . |
| A 030 | Users, who want to read only, must have the unrestricted Read-Only Access | . | . |

## Interactivity

Participation :
| ID | Description | Priority | Assigned to |
| I 010 | To participate in the execises and projects, the user must create an account | . | . |
| I 011 | To have a feedback, the user must enter his/her email address | . | . |
| I 012 | The user must be able to create and to maintain a wiki page | . | . |
| I 013 | A user will be responsible for the content that he adds on the training wiki (including discussion pages) | . | . |
| I 014 | A user has to check back any information, which he gets from the wiki page. On the wiki no dogma exists | . | . |
Administrator :
| ID | Description | Priority | Assigned to |
| I 020 | The administrator must exist for the Training WIKI | . | . |
| I 021 | <Something about administrator's functions?> | . | . |
| I 022 | The administrator must have a privilege to lock or delete the content | . | . |
| I 023 | The administrator must have a privilege to block the account | . | . |

## Non Function Requirements

Non-Function :
| ID | Description | Priority | Assigned to |
| NF 010 | Server Issues and other non-function related issues regarding this project | . | . |

## Other Comments

So now we can arrange the requirements under these headings and start assigning them UniqueIDs. (For example, "LC-010" or "SF-020".)
I suggest another one..."Content". What topics are appropriate to this course, and which are not. For example, this isn't the place to describe every issue in English grammar, nor is it an ESL course. But some of this stuff should be put in...which bits? Similarly, how much detail should be include about using various tools? Is an introduction to XML appropriate in this course, or should we just link to other XML learning resources?
Bart says: >> Similarly, how much detail should be include about using various tools? Is an introduction to XML appropriate in this course, or should we just link to other XML learning resources? Think about your persona :)