Technical writing/Exam02

back to Technical writing

Instructor's Note

This Level 1 exam paper was originally written in a word processor. It has been slightly modified to fit wiki formatting. TWFred 14:38, 2 December 2007 (UTC)

What is the SDLC?

SDLC means Software Development Life Cycle, sometimes it is called the System Development Life Cycle. The SDLC is a series of steps which a company follows to create a new product.

The SDLC often has between 3 and 9 steps, although some have more. I choose to use 4 steps.

Define

The first stage is to define the project. At this stage we ask several important questions:

• What is the aim of this project?
• Is this project necessary?
• What must the project achieve?
• What documentation is required?

Once these questions are answered we move on to the “design” stage.

Design

The design stage is the most important part of the SDLC. It is at this stage that the project will either succeed or fail. This stage requires:

• Project managers, architects and developers working together to create something which is do-able.
• Tests for the product must be defined
• Tests must be realistic and trackable
• Decide what kind of documentation is appropriate

A properly managed design stage will save time and money later.

Once the project has been well designed, we can move to the development stage.

Develop

This stage is where the developers build the system.

In this stage it is important to control “scope creep”. Scope creep is when extra functions are added to a project after the design stage. These extra functions can create delays for the project.

As part of the development stage it is important to run the tests which were defined in the design stage.

During the development stage we also test the documentation for the following things:

• Accuracy
• Appropriateness
• Usefulness

After successful testing we can deliver the product

Deliver

At the delivery stage we release the product to the consumer.

As part of the delivery stage we also review the project in order to improve the processes we use to make new products.

Who is your audience?

If you have a budget, there are many ways to discover who your audience is.

Popular methods are:

• Market research
• Surveys
• Questionnaires

If you have no budget, the best way is to create a “persona”

What is a persona?

A “persona” is an imaginary person who is the stereotype of the kind of person we want to use our product.

Why personas?

We make personas so that a product is built with a particular audience in mind. The aim is not to make as many people happy as possible, but to make our persona happy.

Steps in making a persona

1. Give them a real name – like Jim or Sarah, not a joke name
2. Create a background for them. – family, education, jobs, likes, dislike
3. Give them goals – what do they want in life and how does the product help them?
4. Think about the documentation – will they use it? Is it useful to them?

The most important aspect of a persona is that the person must be believable.

Prague for Beginners

Prague is a beautiful city and has a lot to offer visitors, here are some tips to help you get the most from your time here.

Getting around

The centre of Prague is ideal for walking.

To get out of the centre you can take:

• Metro
• Bus
• Tram

Things to see

A good walking tour of the centre of Prague is:

• Start at the Museum on Wenceslas Square
• Walk to the Old Town Square and see the Astrological clock
• Follow the “Golden Path” to Charles Bridge
• Cross the bridge and walk up to Prague Castle

During your walk you will see some of the city’s historic churches.

Things to try

• Czech food – especially the national dish, pork, cabbage and dumplings
• Czech beer – it is as good as they say!

Things to watch out for

• Pickpockets – they can be a problem if you aren’t careful
• Taxi drivers – they have a reputation for being dishonest
• Confusing streets – it can be easy to get lost, but you will soon see something you recognise

Interviewing an SME

When creating documentation it is important to get accurate information. The best source of that information is an SME, a Subject Matter Expert.

Often an SME is a developer or architect. Always remember that the SME is a busy person and it is important to use as little of his time as possible.

Make arrangements

• When will the interview take place?
• Where will the interview take place?
• What do I need to have with me?

The location of the interview is very important, if you are trying to learn how something works in reality then a meeting room would not be helpful.

Know your stuff

Do some background reading, gather as much information as possible about the subject you are looking at.

• Internet – Google and wikipedia are very useful
• Existing documentation

From your background reading you will be able to prepare good questions and intelligent guesses about the subject.

Be Prepared

• Have your questions written down
• Bring paper and a pen, or a notebook if you can type and listen at the same time
• Bring a camera if diagrams or equipment are involved
• Bring some chocolate to make the atmosphere more relaxed

During the interview

• Don’t waste the SME’s time
• Get to the point
• Make sure you understand the information you’re getting

When it is over

• Thank the SME for his time
• Validate the information he gave you

Illustration of information chunking and sorting.

What is an “information chunk”?

An information chunk is the smallest amount of information which is intelligible within a given context.

That information could be a

• Word
• Sentence
• Whole paragraph.

If you are creating graphic documentation an information chunk could be an image or a sign.

What are “Good” requirements?

A good requirement is:

• Necessary – Does the product really need to perform a certain function?
• Accurate – Is the requirement clearly defined?
• Concise – Is the requirement easily understood?
• Consistent – Does the requirement have room for confusion? If so, then simplify.
• Trackable – Is it possible to see where the requirement is in the SDLC at any given time?
• Testable – Can the requirement be tested accurately?

The words we use in requirements are important:

• Use words like “must”, “will” and “can”.
• Don’t use words like “should”, “may”, or “be able to”.
• Use precise terms.

What is “technical writing”?

Technical writing is developing information which is relevant and useful to a product audience.

That information is taken from an SME and transformed into something the user can benefit from.

Technical writing can be creating the following:

• Written documents such as user manuals
• Graphic guides
• Online help files

The most important thing is that the information is given in a useful and meaningful way to the user.

The aim of technical writing is to help the user achieve his goals.