Best Practices

Entering and growing in this field.

Analyze and Anticipate User Requirements

You cannot anticipate everything that the user wants.
You can predict things that most of the readers will want to know.
Know your audience
For whom are you writing?
What do they already know?
What do they need to know?

1. There needs to be a common understanding between the receiver and the giver. You both must know what you are talking about.
2. Problem stems from ambigu

ities in stating requirements.
3. Often the problem one has in establishing correct requirements is how to get started. And one of the most important things in getting started is to ask questions.
4. Classify your questions. Context-free questions are high-level questions that are posed early in a project to obtain information about global properties of the design problem and potential solutions.
Examples:
Who is the client?
What is the reason for solving this problem?
What environment is this product likely to be deployed?
These questions force both sides - developer and customer, to look at the higher issues. These questions can be prepared in advance.
5. Another important point is to get the right people involved. There is no point in discussing requirements if the appropriate people are not involved in the discussion.
6. What all needs to be done? In establishing requirements, it is important to specifically establish the functions, attributes, constraints, preferences, and expectations of the product.
Usually in the process of gaining information, functions are the first ones to be defined. Functions describe what the product is going to accomplish. It is also important to determine the attributes of a product. Attributes, meaning, characteristics/features wanted by the client. While two products can have similar functions, they can have completely different attributes/parameters. After all the parameters have been clarified and attached to functions, we must determine the constraints on each of the parameter.
Analyzing the user requirement is one of points that gain prominence in preparing a technical document. Requirement gathering is the primary necessity for any product development. Co-relating this, SRS or the Functional Spec takes the first place in any product documentation suite. Let us try to understand this from various perspectives for our cram.

1. What is an SRS?
An SRS is basically an organization's understanding (in writing) of a customer or potential client's system requirements and dependencies. Usually this understanding is arrived at, prior to any actual design or development work. It assures that both the customer and the organization understand the other's requirements.
The SRS is similar to a blueprint for any project. It is the parent document in the entire document suite, since all the other documents like Design document, Architecture document, Test plan etc are totally dependent on this document.
An SRS can contain both functional and nonfunctional requirements only. It is not a design suggestion or possible solutions to technology or business issues, or any other information other than what the development team understands the customer's system requirements to be.

A well-designed, well-written SRS accomplishes the following major goals:
 It provides feedback to the customer about the understanding a development has regarding the user requirements. The SRS is be written in natural language, in an unambiguous manner that may also include charts, tables, data flow diagrams, decision tables, and so on.
 It decomposes the problem into component parts. The simple act of writing down software requirements in a well-designed format organizes information, places borders/emphasis around the problem, congeals ideas, and helps break down the problem into its component parts in an orderly manner.
 It serves as an input to the design document. Therefore, the SRS must contain sufficient detail in the functional system requirements so that a design solution can be devised.
 It serves as a product validation check. The SRS also serves as the parent document for testing and validation strategies that will be applied to the requirements for verification.

2. When is the SRS done?
SRSs are typically developed during the first stages of "Requirements Development," which is the initial product development phase in which information is gathered about what requirements are needed and not. This information-gathering stage can include onsite visits, questionnaires, surveys, interviews, need analysis of the customer etc. The actual specification, then, is written after the requirements have been gathered and analyzed.

3. Why must Technical Writers be involved with SRS development?
Unfortunately, much of the time, systems architects and programmers write SRSs with little help from the Tech Writers. And when that assistance is often limited to an edit of the final draft just before the document goes out the door. Having technical writers involved throughout the entire SRS development process can offer several benefits like:
 Tech writers are skilled information gatherers, ideal for eliciting and articulating customer requirements. The presence of a tech writer on the requirements-gathering team helps balance the type and amount of information extracted from customers, which can help improve the SRS.
 Tech writers can better assess and plan documentation projects and better meet customer document needs. Working on SRSs provides tech writers with an opportunity for learning about customer needs firsthand early in the product development process.
 Technical writers know how to determine the questions that are of concern to the user or customer regarding ease of use and usability. Technical writers can then take that knowledge and apply it not only to the specification and documentation development, but also to user interface development, to help ensure the UI (User Interface) models the customer requirements (eg: Application s/w development).
 Tech writers, involved at this stage can become an information resource throughout the process, rather than an information gatherer at the end of the process.
 In short, a requirements-gathering team consisting solely of programmers, product marketers, systems analysts/architects, and a project manager runs the risk of creating a specification that may be too heavily loaded with technology-focused or marketing-focused issues. The presence of a tech writer on the team helps place at the core of the project, those user or customer requirements that provide more of an overall balance to the design of the SRS, product, and documentation as a whole.

4. What kind of information must go into an SRS?

SRS development is a collaborative effort for a particular project. The Company might have an SRS developed for some other product. That is to say you will have examples to use or atleast a template. But, in case you are starting from scratch ... not to worry … several standards organizations like the IEEE have identified key topics that must be addressed when designing and writing an SRS: They are:
1. Interfaces
2. Functional Capabilities
3. Performance Levels
4. Data Structures/Elements
5. Safety
6. Reliability
7. Security/Privacy
8. Quality
9. Constraints and Limitations

Considering what specifically goes into an SRS, from the above general list, how the SRS is to be structured, where to get started etc. the following items are mandatory for SRS development.

1. A template
2. A method for identifying requirements and related resource
3. Business operation rules and regulations

Automation Possibilities in Technical Documentation

In Technical Documentation, style guides often list out words or terms that are to be used with discretion.

For example, in Microsoft Manual of Style for Technical Publications, 3rd ed., in Part 2, Usage Dictionary, over 180 pages discuss nearly a thousand words. In EMC Technical Publications Content Developer’s Style Guide, the Word Lists section spread over nearly 50 pages discusses a similar large number of words that are not to be used, or used in specific ways in specific contexts. So is the case with HP Software Information Engineering Documentation Style Guide, Apple Publications Style Guide, and Sun Editorial Style Guide.

Now, how would you check your document for the presence of such a large number of words or terms?

White Paper: Simplifying Technical Documentation

Technical documentation includes tasks that are repetitive. Repetitive tasks can be automated to improve quality, consistency, and productivity. An example of such a repetitive, but critical task is identifying and notating product, trade, or service names with ®, ™, or ℠ symbols in technical documents.

This paper discusses TRADEmarker, a Microsoft Visual Basic for Applications (VBA) macro. The macro identifies product, trade, or service names—as they appear the first time—in Microsoft Word documents. The paper also discusses the impact of TRADEmarker on productivity.

Syndicate content