Wikiversity

Technical writing/Requirements analysis

< Technical writing

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
  • <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
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
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
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
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
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
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
Non-Function
ID Description Priority Assigned to
NF 010 Server Issues and other non-function related issues regarding this project . .

Other Comments

edit

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

Retrieved from "https://en.wikiversity.org/w/index.php?title=Technical_writing/Requirements_analysis&oldid=2112739"