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[edit | edit source]

<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[edit | edit source]

**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[edit | edit source]

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[edit | edit source]

**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[edit | edit source]


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[edit | edit source]


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[edit | edit source]

**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[edit | edit source]

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

Other Comments[edit | edit source]

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 :)