Posted on

C# – What is a derived class?

As the name implies, a derived class originates from another class, which in C# is called a base class.

A derived class is a specialization of the base class. A derived class is created from an existing base class. It inherits the member variables and methods of the base class from which it is derived.

For example, if you have a base class Music, you might have a derived class Classical and another derived class StringQuartet.

While Classical derives from Music, and StringQuartet derives from Music, each derived class can represent different specializations of the base class Music.

crone-park (24)

What is a derived class?

When you define a class to derive from another class, the derived class gains all the members of the base class – except its constructors and destructors.

This means the derived class can reuse the code in the base class without re-implementing it.

In the derived class, you can add more members allowing it to extend the functionality of the base class.

  • Base Class – members are inherited by the derived class.
  • Derived Class – inherits those members from the base class.

Each Derived Class Has Only One Direct Base Class

A derived class can have only one direct base class.

However, inheritance is transitive.

If

StringQuartet is derived from Classical

Classical is derived from Music

StringQuartet inherits the members declared in Classical and Music.

Polymorphism and Derived Classes

Polymorphism let us treat objects of a derived class as objects of its base class.

For example, big cats (base class) hunt (a method) in different ways. A Lion (derived class) stalks, while a Cheetah (another derived class) outruns it.

Virtual Methods

A virtual method is a type of method which can be overridden in a derived class.

Tip: use override sealed if you want a virtual method in a base class to become sealed in a derived class.

MSDN Definition

A class that was created based on a previously existing class (i.e., base class). A derived class inherits all of the member variables and methods of the base class from which it is derived.

C+ Derived Class Example

class Derived : [virtual] [access-specifier] Base

{

// member list

};

class Derived : [virtual] [access-specifier] Base1,

[virtual] [access-specifier] Base2, . . .

{

// member list

};

 

Note: In C#, both inheritance and interface implementation are defined by the : operator, equivalent to extends and implements in Java. The base class should always be rightmost in the class declaration.

Single Inheritance

In “single inheritance,” a form of inheritance, classes have only one base class.

Consider the relationship illustrated in the following figure.

PrintedBook

Book

PaperbackBook

Note the progression from general (PrintedBook) to specific (PaperbackBook).

Kind of Relationships

The derived class has a “kind of” relationship with the base class.

Why?

A Book is a kind of a PrintedDocument

A PaperbackBook is a kind of a book.

Book is

both a derived class (from PrintedDocument) and a

base class (as PaperbackBook is derived from Book).

Code Sample

class PrintedDocument {};

// Book is derived from PrintedDocument.

class Book : public PrintedDocument {};

// PaperbackBook is derived from Book.

class PaperbackBook : public Book {};

Direct Base v Indirect Base

PrintedDocument is a “direct base” class to Book.

PrintedDocument is an “indirect base” class to PaperbackBook.

Why?

A direct base class appears in the base list of a class declaration – an indirect base does not.

The base class from which each class is derived is declared before the declaration of the derived class.

Learn more at http://msdn.microsoft.com

Posted on

User Guide Checklist

This checklist summarizes the recommended structure and contents for User Guide documents.

teacher

Introduction

In this section, introduce the User Guide and cover the following areas:

– Intended readers – identify the different user types, for example, system operators, home users, and experts. For each, identify the assumed level of experience and highlight the sections of user guide which apply to them.

– Software version – identify the software release the User Guide refers to.

– Purpose – describe the purpose of both the system and User Guide.

– How to use User Guide document – describe the intended use, section contents and relationship between sections.

– Related documents – identify any related documents.

– Conventions – describe symbols, conventions and syntax conventions used in the guide.

– Problem reporting instructions – provide an email address so readers can contact you if they find an error or omission.

Overview

Outline how the system works at a high level.

– Identify the key functions

– Inputs and Outputs – identify inputs what you, the reader, need to enter, and outputs, what you expect in response, for example, reports.

– Provide further detailed explanation, if necessary.

– Assumptions on user expertise, for example, experience or proficiency in related areas or previous training.

Procedures

This is usually the heart of the user guide. For each task, document the following:

– Explain how to get started, for example, specific settings they need to make to use the application, such as installing a plugin or checking that a specific version of Java has been installed.

– Describe the different functions of the system.

– Provide cautions, warnings, and recommendations.

– For each procedures, identify where in the application you perform this task, input operations and expected results. If necessary, include a screenshot that helps the reader understand the task. Avoid pointless eye candy screenshots.

– Required parameters, optional parameters, default options and order/syntax

– Provide examples

– Identify known issue, likely errors, possible causes, and resolutions.

Reference

Identify and describe all system capabilities, for example,

– Describe the purpose of different buttons on the menu bars, what happens if they get greyed-out, how to change this, why this occurred, and how to reset window layout.

– Describe the purpose of each field, identify mandatory settings, minimum or maximum settings, recommendations, and data input types.

Error Messages and Recovery Procedures

– Document all error messages.

– Identify root cause.

– Suggest recovery procedures

Glossary

Provide list of ambiguous terms or terms users may not know to the reader.

Index

This is recommended for any User Guides of 40 pages or more.

Document Control

Ensure there is Document Control, Sign-off and Change Record information.

Document Structure

Ensure that the guide has the following:

– Headers, footers, navigation bars

– Table of contents

– Index

– Glossary with product terminology and industry terms

– Cross-references/links to related procedures/documents

– Is each topic self-contained? In other words, can you perform the task from start to finish without having to go to another page?

– Is there adequate white space?

– Have you avoided large blocks of text?

– Does the document separate conceptual, procedures, and reference materials?

Visual Information

In addition to text information, provide visual cues to help the reader use the manual, understand concepts, and help them digest information faster.

You can achieve this by using some of the following:

– Headings

– Bullets

– Bold

– Arrows

– Illustrations

Different Learning Styles

Where possible, develop content that supports the following methods of learning:

– Visual

– Audio

– Touch

In addition, provide the following types of examples:

– Concrete examples

– Abstract concepts

Document Format

Produce the user guide in a file format the suits the reader. For example, do they want the document in PDF or as Online Help or both?

Other factors to consider include:

– Size – remember to optimize the PDF before publishing.

– Online/print – prepare the document in both formats if necessary.

– Software/hardware environment – will the reader need any special software to view the documents?

– Binding – if delivering a hardcopy, make sure the binding is reliable, so pages don;t fall out after a little use.

– Coating – if the document will be used outdoors, make sure it is weather-proof.

Posted on

How to Write RESTful APIs

The following example shows how to document an API. This example is taken from the Bing Ads Content API, which is a RESTful API.

b52-bomber

RESTful API Example – Get Single Item

This section describes the type of API and some details about the type of operations it performs.

The Bing Ads Content API is a RESTful API. Standard CRUD-style operations (Create, Read, Update and Delete) are performed by sending HTTP requests to specific URL.

Next, it describes the HTTP request. This is composed of the following:

1. Header containing authentication fields

2. Body containing the data to be acted upon

3. Endpoint where the request will be sent

4. Mandatory or optional query string parameters to be appended to the endpoint URL.

The next section describes the operations and their requirements.

Purpose of Get Single Item

Retrieves the specified item from the product feed.

Note the construction.

1. Start with a verb, in this instance. Retrieves.

2. Identify what is specified, for example, the item from the product feed.

HTTP Request

This is a sample GET request.

GET https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{bmcProviderId}/products/{productUniqueId}

Get Result

request
GData
auth/frontend/provider_unknown
Unknown provider-id in URL: {bmcProviderId}.
Examine the different parts of the string and how it’s constructed.

https

content.api.bingads.microsoft.com/

shopping/

v9.1/

bmc/

{bmcProviderId}/

products/

{productUniqueId}

URI Elements

There are two elements in the URI.

1. bmcStoreId – Replace with your Bing Merchant Center Store Id.

2. itemUniqueId – The unique Id of the item being retrieved, updated, or deleted. This is the fully qualified Id for this item, such as online:US:Sku123.

Query String Parameters

The three items to document here are: Parameter Name, Description, and Value.

warnings

1. Parameter – Warnings

2. Description – Returns a list of non-fatal warnings inside of the <sc.warnings> in the response body.

3. Value – Warnings are off by default. Specify this parameter with no value to enable warnings.

dry-run

1. Parameter – dry-run

2. Description – Performs the requested operation in dry-run mode. The response will contain any applicable errors or warnings, but no live data will be modified.

3. Value – Dry-run mode is off by default. Specify this parameter with no value to enable dry-run mode.

Request Headers

Here we document the Element, Description, and Data Type, for example:

AuthenticationToken – The OAuth access token used to manage Bing Ads accounts linked to a Microsoft Account. All of the data types are string. String.

DeveloperToken – The client application’s developer access token. String.

Password – The Bing Ads user’s sign-in password. String.

UserName – The Bing Ads user’s sign-in user name. You may not set this element to a Microsoft account. String.

Request Body

In this example, we do not supply a request body with this method.

Response Headers

Here we identify the Header Element and provide a description.

WebRequestActivityId – Provides a unique Identifier for the current request to be used for support purposes.

Response Body

We identify the response body which contains the specified items in the product feed format.

HTTP Return

For HTTP Return, we identify the HTTP Response Code, its Name, and a brief description.

1. HTTP Response Code – 200 – OK – The operation succeeded.

2. HTTP Response Code – 404 – NOT FOUND – The specified item ID does not exist.

You can read more about the API here: https://msdn.microsoft.com/en-US/library/bing-ads-content-api-reference.aspx

Posted on

How to Test Technical Documents

This checklist helps you test User Guides and other technical documents.

eye-test

The first step is to ensure the following is in place.

  1. Setup the necessary technical environment. Make sure this reflects the user’s settings or as close to as possible.
  2. Print out the procedures. Follow the instructions as per the document. Aim to identify any gaps in the steps. Likewise, see if additional notes or warnings should be added.
  3. Examine the screenshots. Does these provide real value? Do the screenshots reflect how the window or dialog box are populated? Is there data in the screenshots? If not, replace with something more meaningful.
  4. Does the introduction orient the reader?
  5. Does it highlight the necessary and mandatory prerequisites that must be performed?
  6. Are the sections in a logical order? For example, is it arranged based on the user interface layout or on commonly performed tasks?
  7. Is there an index? Are the entries used in a meaningful way?
  8. If online, have meaningful keywords been added to the search engine?
  9. Comprehensive – are all scenarios covered in the document? In other words, in addition to checking that the materials in the document are correct, you have to consider if other procedures are missing? To do this, you need to examine the application and see if, from a user’s point of view, if all tasks have been documented.

User Guide Checklist

After this, examine the document using the following checklist.

Visual Cues

Have you provided visual cues to help the reader use the manual, understand concepts, and help them digest information faster?

You can achieve this by using some of the following:

1. Headings

2. Bullets

3. Bold

4. Arrows

5. Illustrations

Support Different Learners

Have you developed content that supports the following learning methods:

1. Visual

2. Audio

3. Touch

Examples

Provide the following types of examples to help the reader understand the materials:

1. Concrete examples, for example, how to perform a specific task.

2. Abstract concepts

Document Format

Have you delivered the user guide in a file format the suits the reader? For example, do they want the document in PDF or as Online Help or both?

Other factors to consider include:

1. Size – remember to optimize the PDF before publishing and to ensure it downloads fast.

2. Online/print – prepare the document in both online and PDF, if necessary.

3. Software/hardware environment – will the reader need any special software to view the documents?

4. Binding – if delivering a hardcopy, make sure the binding is reliable, so pages don’t fall out after a little use.

5. Protection – if the document will be used outdoors, make sure it is weather-proof.

Document Structure

Have you checked that the guide includes the following?

1. Headers, footers, navigation bars

2. Table of contents

3. Cross-references/links to related procedures/documents

4. Is each topic self-contained? In other words, can you perform the task from start to finish without having to go to another page?

5. Is there adequate white space?

6. Have you avoided large blocks of text?

7. Does the document separate conceptual, procedures, and reference materials?

8. Index

9. Glossary with product terminology and industry terms

Introduction

In this section, you should introduce the User Guide and cover the following areas:

1. Intended readers – have you identified the different user types, for example, system operators, home users, and experts?

2. Have you identified the assumed level of experience and highlighted the sections of user guide which apply to them.

3. Software version – is the software release the User Guide refers to identified?

4. Purpose – have you described the purpose of the system and User Guide?

5. How to use User Guide document – have you described the intended use, section contents and relationship between sections?

6. Related documents – have you identified related documents?

7. Conventions – have you described symbols, conventions and syntax conventions used in the guide?

8. Problem reporting instructions – provided an email address so readers can contact you if they find an error or omission?

Overview

Have you outlined how the system works at a high level?

1. Identified key functions?

2. Inputs and Outputs – identified inputs what you, the reader, need to enter, and outputs, what you expect in response, for example, reports?

3. Provided further detailed explanation, if necessary.

4. Assumptions on user expertise, for example, experience or proficiency in related areas or previous training.

Procedures

This is usually the heart of the user guide. For each task, document the following:

1. Explain how to get started, for example, specific settings they need to make to use the application, such as installing a plugin or checking that a specific version of Java has been installed.

2. Describe the different functions of the system.

3. Provide cautions, warnings, and recommendations.

4. For each procedures, identify where in the application you perform this task, input operations and expected results. If necessary, include a screenshot that helps the reader understand the task. Avoid pointless eye candy screenshots.

5. Required parameters, optional parameters, default options and order/syntax

6. Provide examples

7. Identify known issue, likely errors, possible causes, and resolutions.

Reference

Have you identified and described all system capabilities, for example,

1. Describe the purpose of different buttons on the menu bars, what happens if they get greyed-out, how to change this, why this occurred, and how to reset window layout.

2. Describe the purpose of each field, identify mandatory settings, minimum or maximum settings, recommendations, and data input types.

Error Messages and Recovery Procedures

Have you identified and described all error messages and recovery procedures, for example,

1. Document all error messages.

2. Identify root cause.

3. Suggest recovery procedures

Glossary

Have you provided a list of ambiguous terms or terms users may not know to the reader.

Index

Have you provided an index? This is recommended for User Guides of 40 pages or more.

Document Control

Have you provided Document Control, Signoff and Change Record information?

PS – if you want the PDF to this, head over to my channel on SlideShare.

Posted on

Functional Specification Checklist

Writing the functional specification occurs after we’ve evaluated the product or technology. If we look at the project planning lifecycle, we can see it’s the second process:

  1. Evaluating products.
  2. Writing the functional specification.
  3. Packaging the master project plan.
  4. Creating the master schedule.
  5. Reviewing Project Plans.

Functional-Specification-Checklist

PS – you can download a Functional Specification Checklist template over here.

Functional Specification Checklist

Before we start writing this document, we need to ensure we understand and check the following:

1. Check if features were deleted from the vision/scope document.

2. Identify assumptions about the solution, customers, and users.

3. Identify dependencies the solution may have on other services, technologies, and people within the organization.

4. Plan how to address security.

5. Identify installation and un-installation requirements.

6. Identify integration requirements.

7. Understand the business case and business benefits.

8. Identify the solution’s high-level architecture.

9. Identify the solution’s components, including how they relate to other components.

10. Identify naming standards it must follow.

11. Identify security guidelines that the solution must follow.

Inputs

To write the Functional Specification, the following inputs are required:

1. Vision/scope document

2. Requirements documents, including:

3. Business requirements.

4. Operations requirements.

5. System requirements.

6. User requirements.

7. Product and technology evaluations

Outputs

After writing the Functional Specification, the following outputs are generated:

1. Design documents, including:

2. Conceptual design.

3. Logical design.

4. Physical design.

5. Functional specification

Best practices

1. Avoid scope creep.

2. Use the vision/scope document to integrate the business goals.

3. Trace features back to the original requirements.

Posted on

How to write a Use Case

This tutorial explains how to write a use case.

use-case-actor

This is Herman, he’s an Actor is our Use Case tutorial. Read more what he does here.

What is a use case?

A use case is a sequence of actions that provide a measurable value to an actor. Another way to look at it is a use case describes a way in which a real-world actor interacts with the system. In a system use case you include high-level implementation decisions. System use cases can be written in both an informal manner and a formal manner. Techniques for identifying use cases are discussed as well as how to remain agile when writing use cases. http://www.agilemodeling.com/artifacts/systemUseCase.htm

A use case describes how an actor uses a system. An actor may not be a person, it could be a banking system, for example.

Use Case Definition

1. One or more scenarios.

2. Self-contained procedure.

3. Independent of other use cases.

4. Starts with the system in a stable state.

5. Ends with the system in a stable state.

6. Identified by the goal of the actor.

7. Contains no time gaps in the flow.

Use Case Benefits

1. Change manual processes into automated processes.

2. Deeper understanding of business processes.

3. Ensure the delivered software works as per the original requirements.

4. Establish an agreement about system requirements.

5. Expose items outside of project scope.

6. Identify alternatives, exceptions, undefined terms, and outstanding issues.

7. Identify gaps between requirements and delivered software.

8. Improve communications between project stakeholder and development team.

9. Prioritize work.

10. Recognize patterns in functional requirements.

Use Case Structure

A use case is comprised of:

1. Actions, Numbers – numbering actions will help readers follow the process flow and, when you are reviewing a use case, help identify a step. Numbering actions improves traceability from requirements to design and testing.

2. Active Voice – it’s important to understand why the active voice is more appropriate than the passive voice when writing use cases. In general, the active voice is more immediate, more confident, and identifies who does what. The passive is fine, and necessary, in different circumstances, for example, if you want to deflect blame from someone. Using the active voice also mean the word count will be reduced, which is important if your use case is very detailed.

3. Alternative Flows – identify branches from the main flow to handle special conditions (i.e. extensions). For each alternative flow, reference the branching step number of the normal flow and the condition which must be true for to execute the extension

4. Alternative Paths – identify the steps to handle variations.

5. Assumptions – identify any assumptions that were made in the analysis that led to accepting this use case into the product description.

6. Attributes – in addition to information such as the actor, direction, and events, you can improve the usefulness of the use case by including project-related attribute information, such as priority, complexity, author, and iteration.

7. Automate use case process – depending on your needs, and the volume of use cases you’ll be creating, you should explore an automation process where you and others can generate use cases on the fly, if necessary. The downside of course if the associated cost, training, and additional overheads. But if you plan to develop use cases on a frequent basis.

8. Brevity – as Shakespeare reminds us, ‘brevity is the soul of wit.’ Brevity in this sense meant intelligence, and this should apply to the title of your process. Keep it short, meaningful, and concise. Actually, see if there is some way to reduce the word count without the title losing any meaning. When we see it like this, rules such as use 2-7 words become meaningless. Use as many as need – but no more.

9. Check, Check again – is it complete? Have you checked that all requirements, business rules, and other specifications are addressed in the use case? Use a traceability matrix to determine (i.e. map) from the requirements document to the use case, otherwise you risk assuming everything has been covered. One suggestion is to use the same ID numbers across both documents, checking them off as you prepare the documents.

10. Colour combination – as well as using clear fonts, when creating images for the use cases, such as process diagrams, use a colour combination with a strong contrast. I know black and white can seem jaded, but if don’t well can look very sharp and powerful. The opposite is backgrounds with dark colours, such as teal, purple, and green, which may have looked trendy at one point but look can look dated and amateur.

11. Consistent – have you ever read a document and found yourself stopping and starting because the tone, phrasing, and terminology keeps changing? This sometimes happens if more than one person is involved in writing the use case. Terms, phrases, and style all change. From a reader’s point of view, it’s distracting. The alternative to this is when words, phrase, style, and even layout are consistent. Strive for this and your readers will thank you.

12. Create a user story – you can help orient the reader by including a brief user story. This should identify who is doing what and why. Keep it specific, brief, and non-ambiguous. The mistake many process writers make is to repeat what’s in the title of the procedure. This adds little or no value. At worse, it adds clutter and wastes the reader’s time. The use case story isn’t required as the use case steps should explain the process. However, most readers are running against the clock. They don’t want to read the entire use case to figure out if this addresses what they were looking for. For this reason, a short user story helps the reader determine if they wish to read the rest of the use case documentation.

13. Diagram – the most useful use cases, from the user’s perspective, include both text and diagrams. They can see at a glance how the process works, and then examine the text to get more granular information. Images, such as process flow diagrams are not mandatory but very helpful. They encourage discussion and allow you to see gaps faster, from m experience, than reading the text. Diagrams don’t need to be works of art. You can create them in PowerPoint or use the yEd graphic editor. One tip – if you create a large diagram, change the page to landscape so it fits better.

14. Events – identify the steps that the actor and system must go through to accomplish a goal. Make sure to identify the flow (i.e. direction).

15. Exceptions – identify errors that may occur during the use case execution, and how the system will respond to those conditions.

16. Exceptions – identify the steps to handle errors and exceptions.

17. Fonts – use a font that is easy to read, renders well on different devices, and doesn’t degrade when converted to PDF. Saying that, I personally try to avoid serif fonts – those like Times Roman with ‘feet’ – as they take took more space that sans serif fonts.

18. Frequency – identify how often will the Use Case will be executed.

19. Identify Goals. A name like Process Invoices doesn’t tell us what’s being done – is it collections, organization, auditing, or some other function? A more insightful name would be Collect Late Payments From Customers. The goal in this example is to collect payments from delinquent customers. The second name does a much better job of defining what the user is trying to do when they perform the use case.

20. Identify specific goals – what we mean here is that you name each use case so that it another person, who is unfamiliar with the document, would know what to expect if they examined it. This means we need to avoid generic and ambiguous titles, such as credit card process, and instead be more specific, for example, credit card application process for new customers. After all, this process may be slightly different than the process for existing customers who are already pre-qualified.

21. Includes – identify other use cases that are included (“called”) by this use case. Common functionality that appears in multiple use cases should be documented in a separate use case.

22. Library – once you’ve created the use cases, I’d suggest you create a dedicated space on the network and upload the files here. If you leave them in MS Word, turn on Track Changes. If you save them to PDF, make sure reviewers have the option to leave comments.

23. Naming convention – one way to achieve this is to create an intuitive naming convention that allows you and other writers to identify High, Medium, and Low use cases. You can also create an Excel spreadsheet to keep track of these, filter the most important, and work on these first.

24. Post-conditions – describe the state of the system after the use case is completed. In other words, now that the process is completed,

25. Pre-conditions – describe the state of the system before the use case starts. This is the baseline of the use case, so to speak. It’s where, for that specific use case scenario, the actor started their respective process. A precondition is one or more criteria which must be true for the use case to start. A precondition represent a type of contract. If the criteria do not exist, the use case can not start. For example, an applicant must be over a specific age to open a bank account.

26. Present Tense – put yourself in the shoes of the person performing the action. Are they in the past, present, or future? In the present, right? They’re performing the action right now. For this reason, write in the present tense. State what occurs here and now.

27. Prioritize – before we start the actual writing of the use cases, identify the most important use cases first, and prioritize these over less critical use cases.

28. Source File – as most everyone has MS Word, it might be best to save the source file in this format. If you save it in another tool, and only have a limited number of licenses, then you may box yourself in as the person responsible for updating the files.

29. Special Requirements – identify additional requirements, such as nonfunctional requirements, performance requirements or other quality attributes.

30. Title – add a sentence long title to the top of the use case.

31. Trigger – identify what initiates the use case. This is the event which causes the use case to start. For example, the bank receive an application form by email.

32. Verbs – it’s common practice to use verbs to describe the process title, but that’s not enough. In addition to using verbs, we need to use the most appropriate verb, the one that brings us as close to the action as possible. So, for example, instead of writing, Create Bank Loan, we can improve it with Validate Bank Loan application. The point here is that in addition to processing a bank loan application, we’re going to validate it.

33. Writing examples – these can help first time writers get started. Provide some sample text, verbiage, and instructions can help novices get started. A suggested format could be as follows: <time or sequence factor>…<actor>…<action>…<constraints> An example may be as follows: At any time after the sales clerk gets the payment, he may update the account.

34. Writing guidelines – it’s recommended to provide some guidelines on how to write use cases. However, there needs to be some flexibility. If your style guidelines are too rigid or formal, your colleagues will spend time (lose time) making sure they adhere to the guidelines instead of focusing on documenting the process. The benefits of an informal style guide cancel out the disadvantages of delays and omissions, which often occurs when people struggle with inflexible guidelines.

What is an Actor?

An actor defines the boundary of the system. The point to note here is boundary.

The components of the system are not actors. For example, a CRM system is not an actor. As the database that stores system information is part of the system, it cannot be an actor.

An actor is:

1. Outside the system being modelled

2. Characterizes a role, a system or some external entity

3. Linked to one or more system use cases

4. A non-overlapping logical grouping of use cases

How to Identify Potential Use Cases

Constantine and Lockwood (1999) suggest that you can identify potential services by asking your stakeholders the following questions from the point of view of the actors:

1. What are users trying to accomplish?

2. What do users need to be able to do?

3. What are the main tasks of users in this role?

4. What information do users need, for example, to create, request, update, or delete something?

5. What information does the system need to give to the user?

How to describe Use Cases

To describe a use case, you need three things:

1. Actor – The actor or actors involved. An actor is a type of user (for example, bank customer) that interacts with the system. The actor is external to the system. Actors don’t have to be people. They can be other systems. For example, the ATM to connect to the customer’s bank. External systems that interact in a use case are also actors.

2. System – The system being used, for example, the ATM. The actor describes a role that users play in relation to the system. Maybe the bank customer is an accountant, but that doesn’t interest us. What interests us is his relationship to the system.

3. Goal – the goal that the actor achieves by using the system. The goal is determined by the actor’s needs.

PS – you can get a good use case template here.

Capturing Use Case Scenarios

Once we understand the actor and the goal for a use case, and have identified key use case scenarios, we can begin some high-level interaction design.

Actors interact with the system by pressing buttons, typing into boxes, clicking on icons and so on to achieve the goal of the use case. A classic mistake made at this early stage of design is to go into technical detail and commit to a specific user interface design or implementation technology.

This is usually the wrong time to make these low-level design decisions.

First, we need to understand what the business logic of the interactions are, then focus on satisfying the business goal of the use case.

An effective way to write use cases is to divide the actions into columns:

1. One for each actor and

2. One for the system.

This lets you see who does what and the order of events in a scenario.

These use case descriptions – one for each key use case scenario – form the basis of high-level object oriented design, the UI design, system test design, user documentation and other useful things we might need later in the development process.

How to Write a Use Case

Write the steps in a use case as follows.

1. Identify who is going to be perform the action, for example, new and existing customers are going to apply for a bank loan.

2. Pick one of those users, for example, new customers.

3. Define what that user wants to do. Each thing she does becomes a use case.

4. For each use case, identify the normal course of events when that user applies for the loan.

5. Describe the basic course in terms of what the user does and how the system responds.

6. Identify alternate courses of events and add those to “extend” the use case.

7. Look for common actions among the use cases. Extract these and note them as common course use cases.

8. Repeat the steps 2 through 7 for all other users.

What else would you add?

Next week we look at how to write technical specifications.

PS – the best book about Writing Effective Use Cases is this one.

Posted on

Difference Between Run and Execute in Technical Documents

Technical writing is about getting the small details right.

The difference between the almost right word and the right word is the “difference between the lightning-bug and the lightning.” Mark Twain

So, when writing a user guide, should you say, Run or Execute?

From one angle, it doesn’t seem to matter. Everyone knows what you mean, right?

Well, maybe.

What’s important are:

  • Readership – who is reading the document?
  • Context – where are you using the verb or phrase?
  • Consistency – are you using the phrase or verbs consistently in other documents?
  • Run and Execute are neither good nor bad.

It’s knowing when to use them that matters.

So, when do you use Execute instead of Run.

Run v Execute as Nouns and Verbs

First, nouns and verbs…

As a noun:

An executable is a file with an .exe extension. For home users (i.e. non-techies, your Mom, your Dad), use program file instead.

Try to use executable and .exe as adjectives, not nouns.

Use the article ‘an’ with .exe, for example “an .exe file.”

Good

an executable program

the program.exe file

Not so good

an executable

program.exe

Execute v Run for Target Readers

Again, for home users, avoid using execute except to follow the user interface. Use run instead.

Use run when describing macros and queries.

Good

To run the program, click Execute.

You can pause Disk Defragmenter so you can run other programs.

Not so

Stop Disk Defragmenter to execute other programs.

Exceptions

The exception is when writing technical documents for software developers who seem to prefer to use execute instead of run. Run seems to be used more for reports and batch files.

Run is preferable, however, where it does not cause any loss of meaning.

Examples of where Execute is preferred

Executing in SQL, for example.

Executes a command string or character string within a Transact-SQL batch, or one of the following modules: system stored procedure, user-defined stored procedure, CLR stored procedure, scalar-valued user-defined function, or extended stored procedure. The EXECUTE statement can be used to send pass-through commands to linked servs. Additionally, the context in which a string or command is executed can be explicitly set. Metadata for the result set can be defined by using the WITH RESULT SETS options.

See: http://msdn.microsoft.com/en-us/library/ms188332.aspx

Methods – IUICommandHandler::Execute method

Responds to execute events on Commands bound to the Command handler.

See http://msdn.microsoft.com/en-us/library/windows/desktop/dd371489(v=vs.85).aspx

As an example, you might want to assign all dynamically generated code a very limited set of permissions, such as Execute (which permits the assembly to execute, but severely restricts what that code can do).

When to use Run? During Runtime?

Rachel Appel writes, “Windows 8 is changing how and when applications run, and you’ll want to understand the nuances of the new application lifecycle

All Windows Store apps have four states: not running, running, suspended and terminated. When you launch an app, it runs. Background tasks are lightweight classes that run periodically, under certain restrictions, while the app is technically not running.”

See http://msdn.microsoft.com/en-us/magazine/jj660301.aspx

Run Your App

Run is most always used when describing an app, or something you do with an app. Look at this example:

When Xcode launches your app in debug mode, it immediately starts a debugging session. If you are running an iOS app, Xcode launches it either in iOS Simulator or on an iOS device connected to your Mac. If you are running a Mac app, Xcode launches it directly on your Mac.

https://developer.apple.com/library/ios/documentation/

Example – About deploying and running apps in the emulator

When you run an app for the first time in the emulator, the following events occur:

  • The emulator starts.
  • The emulator loads the operating system.
  • The emulator displays the Start screen. Your app is deployed to the emulator.
  • Your app runs on the emulator.

That help?

Let me know if you have any questions.

 

Posted on

10 Ways To Improve Your Documentation Plan Right Now

documentation-plan-improve

One of the difficulties when creating documentation plans is determining the correct figures for the amount of work involved. For example, if you’re creating a user guide for an application you know quite well, then it’s easy to estimate the amount of work involved. And if you’re doing the writing, then you can also gauge how fast you can write the documents.

But what happens when don’t know the specs, haven’t seen the software, and won’t be writing the documents?

Here are some things to consider:

  1. Requirements – have these been signed off yet? If not, flag that your dates are based on the current requirements and will change if the requirements are modified. This is probably the most serious factor to consider when estimating the amount of effort required.
  2. Scope – clarify what is in the scope of the document plan and also what will not be delivered. Why? This removes any assumptions other line manager and business owners may have. If they want to change the scope, then fine, you can do that but it means updating the document plan.
  3. Software – make sure you have licenses for any authoring tools before you start, for example, if you’re running a globally distributed team and you want everyone to use the same version of FrameMaker. Otherwise time will be lost.
  4. Deliverables – do you need to develop both PDF and/or online help? While, in theory, both of these can be created from the same source, there is usually some extra effort to refine the PDF and to save them in the correct directories if you plan to share them from the online help.
  5. Revision – if the documents will be revised by subject matter experts, who are not under your control and who may impede your progress at some point, allow time to chase up these parties and, if necessary, allow time to show them how to use revision software or the revision tools in applications such as Acrobat.
  6. Conditional Text – if you plan to conditionalize the content allow time to check the outputs if the content will be significantly different.
  7. Resources – identify the names and roles of team members and confirm if these have been assigned to the project.
  8. Activity breakdown – list all of the documents and content types you plan to deliver. For example, User Guide in PDF and Online Help, Release Notes in PDF only. Admin Guide in Online Help only. If it helps, create a matrix to illustrate what will be delivered. Note that you may also factor in other deliverables and formats, such as for mobile devices if this will require extra effort.
  9. Time estimate – identify the start and end dates and, most importantly, any dependency you have on other departments. For example, if Development is late in providing working software, does this affect your timelines? If Business Analysts are late or change the requirement, what impact will this have? If Tech Support is unable to provide a staging environment to test the online help, how will this affect your dates?
  10. Printing and Production – if you have to outsource the printing, and for example, packaging, then factor in the costs and turnaround times. Also include any contingencies if they are unable to provide this service for whatever reason.

Documentation Planning

Essentially this is just common sense, isn’t it?

From one angle it’s a project plan for a set of documents. What you need to be aware of are any potential impacts on your schedule and interruptions that may undermine your efforts.

For example, if you are writing two sets of documents for two different projects at the same time, allow for the fact that the stopping and starting and switching from project to project will interrupt your progress as you lose momentum every time.

You need to anticipate things like this as on paper it should make no difference, but in the real world it will undermine your efforts.

PS – Download your Documentation Plan Template here.

Posted on 10 Comments

5 Ways To Differentiate Yourself as a Technical Writer

technical-writer-standout

Feeling ignored? What’s that? No pay respects the hard work you do as a tech writer.

Sad, isn’t it? Very sad…

Ever wonder why?

Ever wonder what you need to do about it? Hmmm?

Tom Peters says, “the value of services will continue to fall” and that the only way to survive is to differentiate yourself from the competition.

Is this true?

How do you as a technical writer make yourself stand out from the crowd? If you don’t, what impact could this have on your career?

How to Differentiate Yourself as a Technical Writer

Here are five suggestions to do this:

  1. Video Blogging – use your Camtasia skills to create videos that show how products work. Cisco is doing a great job in this area. They gave flip cameras to the IT people and encouraged them to make short, snappy videos that show how to use their hardware, networks, and systems. Which would you prefer? To read 20 pages or watch a 3 minute video?
  2. Screencasting Training – now that you know how to make the videos, why not use this to teach others to do this same. Position yourself as a screen-casting expert, setup the blog, get involved, and show others how this works. FWIW there is a very active video marketing group on LinkedIn (http://www.linkedin.com/in/ivanwalsh) that you may want to join.
  3. Web-based Training – if you’ve spent years writing guides, you must have developed an in-depth knowledge of 2 or 3 fields. See which of these are most in demand (Google searches and forums will be a starting point) and then develop training modules that you can present online. Lynda.com does a great job in offering training over the web. Sign up with them and see how it works.
  4. Social Media Writing – you know how to write, right? Well, most people don’t. As Social Media continues to explode leverage your writing skills and show (“the benefit o f communicating well on Facebook is…”) others how to get their message across on these Social Network.
  5. Business English – the upside of all these jobs getting shipped to India, China, Brazil is that their Management teams want to do more business in the west. How can you help them write better reports, communicate more clearly, protect them from being misunderstood – you get the idea!

These are just five ways you can stand out from the crowd and position yourself as a specialist. My suggestion is to look at who is doing this right, e.g. Debbie Weil, and study them diligently. Then develop an action plan and start getting the rewards you deserve.

What other careers can you think of? Is it possible to differentiate yourself as a Technical Writer? How would you do it?

PS: Tom Peters is here: Thriving on Chaos: Handbook for a Management Revolution

Posted on 7 Comments

Who Makes More Money? Technical Writers with Language or IT Skills?

money

Kai raised an interesting point about which skill (writing or technical) takes longer to master.

Knowing how to structure and present information to users? Or knowing how to use a product or application? That got me thinking. If you want to make money as a technical writer, which area should you focus on?

Sharpen your writing skills or deepen your technical knowledge, for example, learning how to document an API?

Which Technical Writers Makes The Most Money

I think there is more money if you have deep technical knowledge rather than strong writing skills.

Kai’s point is, “…it’s always been easier and faster to learn a product/app. So knowing about structuring and presenting information has been the more valuable skill in a writer – and the rarer one, too, that’s much harder to learn from colleagues!

So I agree with David: “… it’s easier for a good non-technical writer with an interest in technology to become a good technical writer, than it is for a good engineer to become one.”

… and with Ivan, that writers can make up deficiencies with interest: “… if someone has an interest in sharing how the technology works, then they will go the extra mile…”

I think the real issue is this:  Which skill takes longer to master?

I have to admit, that’s a very good way of looking at it. I hadn’t actually thought of it in those terms.

  • My take is that it’s easier to develop language/writing skills… or at least to develop them to a level where you can perform your duties as a technical writer.
  • With technology it’s more complex as (at least for me) I’m always learning. Even in areas where I have considerable knowledge, I still find that I’m learning and finding better ways of doing things.
  • When I started out my writing skills were rather ‘unsophisticated’ and that’s being kind. But, I knew how to program (Cobol, C, Fortran) and landed some nice contracts as a results. Writers with much better qualifications weren’t even considered.

I think there is more money if you have deep technical knowledge rather than strong writing skills.

What do you think?

Posted on 4 Comments

Stephen King Can Make You A Better (Technical) Writer

Scott, over on Words on a Page, says, “If you want to improve as a writer, you not only need to write. You need to read. Writing and reading are two sides of the same coin. You need to do both to achieve your potential.”

I head downtown most weekends and buy 2 or 3 books, mostly business, history and some fiction.

Every so often I run out of options (we’re in Beijing) and get something I usually wouldn’t buy, for example, Iain M Banks. Reading outside my comfort zone stretches me. I encounter writing styles, opinions, and  information that I usually side-step.

Scott adds that by reading, ‘you’re exposing yourself to different voices and viewpoints. And you can pick up some new techniques. Not only that, you get a great opportunity to see what other writers are doing well and what they’re doing badly.’ This brings me to dear ol’ Stephen King.

How Stephen King Made Me A Better Technical Writer

I’ve read Stephen King (on and off) since I was a teenager-almost 30 years. After going through Jack London, King Arthur and HG Wells, he was the first modern author that I read.

What did I like most?

The tension, crisp writing and little details that sucked you right in. You had to read on. Would Cujo eat the small child? Most of this was horror, something I grew out of after high school.

But he also wrote another book, On Writing.

If you’re interested in the mechanics of writing, get your hands on this. For me, it’s his best book — and I wish he’d go back and read it.

Why?

Because it teaches you how to write tight prose, remove the waffle, and stay focused. All the things I try to do as a technical writer.I hope he’ll turn a corner someday which is why I give him so many second chances…

What am I reading now?

I tend to mix and match. I have a stack of books next to my bed and dip in and out.

Some are:

  • Groundswell, Social Media book
  • Built to Last – what makes companies success over the long term
  • Stephen King – Duma Key, really lame, especially after his early stuff
  • Graham Greene is always a pleasure. Our Man in Havana is a favorite
  • Plato’s Apology
  • Genghis Khan bio, life in ancient Mongolia
  • Margaret Atwood’s The Handmaid’s Tale
  • Iain M Banks – pretentious drivel! I had such high hopes. Philip K Dick is the best sci-fi writer for me.
  • Catch 22 – ok, bit dated
  • Al Ries, Focus and the 22 Immutable Laws of Marketing
  • Tom Peters, Peter Drucker and Seth Godin are all there too.

Seth’s writing style is, for me, the best out there right now, at least in the business world. Tight, crisp, and funny. No words wasted.

I rarely buy magazines anymore as most are close to 5 euro in Europe. Instead I pony with the difference and get some books.

How about you? What are you reading?

Posted on 5 Comments

How I Set Priorities: Get Things Done

Ross Kimbarovsky asks: “How do you decide what to do next? Should you write a blog post? Answer emails in your inbox? Make several sales calls? Spend time on Twitter? Or should you call a team meeting to discuss a customer problem?

Ross adds that successful people are successful in part “because they are good at setting priorities. And while there are many different ways to set priorities, I wanted to share how I set my own priorities.”

Getting Things Done – How I Set Priorities from Ross Kimbarovsky on Vimeo.

Getting Things Done: How I Set Priorities

For me, it’s all about planning. And planning, by extension, is decision-making.

  1. Start the night before. At the end of the day, I review what I’ve done. It takes only 5 min. What did I forget to do? This goes to the top of next day’s schedule.
  2. I get up around 5.30 am to get a head start and beat the kids getting up.
  3. I ignore the emails for 1 hour. Nothing is that urgent.
  4. I plan my day – what is critical goes first, then what I need to do and the rest can wait
  5. When all of this is done, I check emails, watch cats doing ninja tricks and what not
  6. I have a super quick review at 11.45 before lunch
  7. I have a super quick review at 2.45 to make sure I’m still on track.

All this is done on my pad. Writing it down seems to make it more permanent. I like to cross things off when I’ve conquered a task!

Small rewards as we go along. Nothing fancy.

Closing my inbox during the work day was/is the biggest way to save time. And, of course, turn off the phone.

How do you organize your day?

Posted on 6 Comments

How to Run (Structured) Interviews

interviewsIt’s not the questions you ask that matters, it’s the way you ask them. Technical writers, business analysts, and developers all ask questions.

They want answers.

And some are better than others. Some ask many times to get the definitive answers. Others think they have the answer but, on closer inspection, have overlooked some vital point. So, how do you ask the right questions?

Structured Interviews & Task Analysis

When working on business transformation and outsourcing projects, I’d spend endless hours interviewing people.

The more I did it, the more mistakes I saw in my interviewing techniques.

I wasn’t getting the answers I wanted. I was losing time and getting bogged down with thorny SMEs. My manager suggested I look at Structured Interview techniques.

  • Structured Interviews are a quantitative research method commonly employed in survey research. It helps ensure that each interview is presented with exactly the same questions in the same order. We used it for Process Design work and developing Action Plans.
  • Answers can be reliably aggregated and comparisons made with confidence between sample subgroups or between different survey periods.
  • Structured interviews allow you to collect data for a statistical survey, for example, data can be collected by an interviewer rather than through a self-administered questionnaire.
  • Standardizes the order in which questions are asked of survey respondents, so the questions are always answered within the same context.
  • Minimizes the impact of context effects, where the answers given to a survey question can depend on the nature of preceding questions.
  • Used as a qualitative research methodology. These types of interviews suit focus group studies in which it helps to compare/contrast participant responses in order to answer a research question.
  • For structured qualitative interviews, interviewers develop an interview schedule which lists the wording and sequencing of questions.

Later, I organized workshops on Structured Interviews where we showed Business Analysts how to interview SMEs and glean the information they needed.

How To Ask Questions for Technical Documentation

Tom Johnson also discusses how to ask questions, for example, to define the topics for an application, ‘Regardless of how many topics you decide to include in your help, asking questions is a tool that can serve you well in all areas of life.’ http://www.idratherbewriting.com/2010/02/17/the-art-of-asking-questions/

How To Ask Questions

Some things to consider are:

  • When to ask Open v Closed questions, i.e. which is the most appropriate.
  • How to interview groups, i.e. how to ensure that quieter types get heard and not bullied/intimidated at workshops and
  • How to verify what the person said is what they actually meant to say..

The final one is much more difficult than you’d think.

How do you interview people?

What mistakes do technical writers make when interviewing? Do they ask too many questions? Or assume they have the information? How do you cope with difficult people at interviews?

Posted on

Robohelp: Why Short Topic Names Improve Navigation

The length of the topic title, i.e. the number of characters, needs to be considered when creating topics for online help.

fuel-signLet’s say you’re creating different topics in RoboHelp. Procedures, reference, and conceptual materials. Each of these needs an intuitive and meaningful name. That makes sense.

However, you also need to consider the length of the topic title (i.e. the number of characters) when it appears in the side Navigation.

The side Navigation appears on the left of the Help system when viewed online.

Topic Title: Name Length

The problem with the length of the topic title is that, depending on the user’s settings, they may only see the first two or three words.

So, if I wrote:

the length of the topic title

they’d only see

the length of [and the rest would be hidden behind the frame]

which isn’t much use.

One way to fix this is to frontload – put the most important word or phrase first – and then add the rest. For example:

  • [6 words] Topic Title: Length of the Name or
  • [5 words] Topic Title: Length of Name or
  • [4 words] Topic Title: Name Length

Remember, users scan for information. If you frontload the critical word, term, phrase, or verb, the user is likely to find the relevant information faster. It also means they don’t have to drag the navigation pane to see the rest of the topic title.

This may not seem important – can’t they just drag it? – but with more of us reading content online, using different devices, different browsers, and on small screens, making the user have to work harder to find information is best avoided.

Remove clutter from headings

A second tactic is to delete filler text or phrases that add little value.

In the example above, we reduced the word count from six to five to four. Was anything lost in the process? Not much.

You can also delete filler phrases, such as Descriptions in Reference Descriptions of the XXX Window, as description is implied. In other words, the user knows they’ll be getting descriptions of the window, for example. Likewise, words such as Information can also be deleted.

A final suggestion is to remove definite articles.

This reduces:

Reference Descriptions of the XXX Window

To

Reference for XXX Window

These are different ways to reduce the length of the topic title and the number of characters when creating online help.

With that said, what’s more important is not to reduce or change the headings to make them shorter but understand why we need to do this. How can we improve the help system for the user?

Maybe there’s a smarter way to create topic headings.

Let me know.

Posted on

Using Weight Scoring Models for Technical Documents

perfectRecently, we looked at how to determine the quality of your technical documentation.

We suggested an approach where you:

  • Identify the scope
  • Identify quality criteria
  • Review a sample of documents
  • Create a baseline
  • Expand the scope

All this makes sense. However, we also need to look at how to define a fair scoring system.

Why?

Some writers have heavier workloads, others writer more complex materials, others may be clever enough to superficially complete their documentation, but not provide the depth of quality we need.

So, how do you address this?

One suggestion is to apply weights to different criteria. For example, let’s say one criterion is for the Executive Summary.

If it exists, you award one point. If not, zero.

However, this is still pretty crude and doesn’t give us much insight into quality.

An alternative approach is to give this criterion a fixed score, ranging from 1 -5, with five as the highest.

Or.

Sum the numbers for the document and award a percentage, say 1-5% for the quality of this piece. This is known as a weight scoring model.

Weight Scoring Models for Technical Documents

This approach allows you to determine the relative success of your product, in this case your documents, based on several criteria. To do this, you need to:

  1. Identify criteria for the selection process, ie what needs to be measured.
  2. Assign weight (i.e. percentages) to each criterion. The sum total must be 100%.
  3. Assign scores to each criterion for each type of deliverable, eg guide, online help etc.
  4. Multiply scores by weights and get the total weighted score.

However, what’s important is not which approach to take but to step back and see which is more appropriate for your quality initiative. You might also consider adopting an approach that’s simplest to roll out as you’ll have some data coming in and, if you start small, you can use this as a building block for larger rollouts.