Author: Theresa Pojuner

I was reading about Agile and Scrum methodologies for project management when I came upon the term ‘User Story’. As an introduction, Agile is a methodology used for software development projects. It provides more control than just stepping through the analysis, design developing, testing, and implementing stages of a project as a whole. The Agile methodology breaks down each stage into subsets so that there is more communication, collaboration, feedback and discussion as each stage is completed. The Scrum methodology (a subset of Agile) is where each piece of a project is worked on as individual tasks for more accuracy and control.

A User Story (a further subset of the above methodologies) is a single sentence that describes a particular task that needs to be done. This need will define a particular project. As an example, suppose a manager is having trouble finding certain information on an employee. The manager may write the following sentence: ‘as a manager, I would like to find employees with have not taken any sick days so that they can be given an award.’ That sentence or User Story is then brain-stormed to understand what the manager is requesting and to discuss details as to how to accomplish the task. All subsequent ideas and solutions are noted and prioritized. The brain-storming sessions will also discuss items such as requirements, functionality, time, cost, tools, resources, due date, testing, etc., but not all in one meeting; each item is done separately and documented.

A User Story is not a Requirements Specification. The Requirements Specification is much more detailed and is basically an agreement which ensures that the client and the project managers are all on the same page. As a whole, it describes the project and outlines the client’s requirements and expectations up front.

In comparison, a User Story is brief and describes what the user wants in one sentence. If a User Story is long or needs to be broken down further (e.g., as a manager, I would like to find employees who have not taken any sick nor personal days so that they can be given an award), then it is known as an ‘epic’. The ‘epic’ will then be broken down into simpler sentences for clarity (e.g. as a manager, I would like to find employees who have not taken any sick days so that …. And as a manager, I would like to find employees who have not taken any personal days so that …). In other words, a ‘to do list’ is created. This list is known as a ‘product backlog’ and will be prioritized and managed by a product/project manager or technical writer. During various stages of the development, more User Stories (‘to do lists’) will be created either by the user, developer, or manager.

Are User Stories useful? Some say yes as it drives or communicates what a client wants and sets the stage for accomplishing individual tasks to complete a project, but others say that without the Requirements, Functional, or Technical Specifications, it is difficult to see how the finished product can be completed. No matter which methodologies are applied or what form of documentation is created, the written material should be able to explain in a concise and clear manner what was requested, how to accomplish it, and be focused on getting what the customer needs and that is what is important.

How do you manage your documents to provide consistent and accurate communication? Depending on your organization, how do you control documents in your Technical Communications or Technical Writing Department if some groups or branches have different procedures for writing, gathering data, maintaining, verifying, or even for getting feedback? This can occur in an organization that is involved with a lot of different products. Think of a manufacturer which sells various electronics or other goods all over the world. Each division has to have their own set of priorities, procedures, guidelines, manuals, etc. What do you have to take into consideration in order to handle all the documentation that has to occur for each area?

Here are some things to think about and questions to ask before deciding on how to manage documents, from choosing a CMS (Content Management Tool) to developing your own methodology:

• Will it be able to manage master documents that will be reused in other documents?
• Will it be able to manage reviews, approvals, automatic notifications, version control, sharing, project plans (for meeting timelines), various image-type files, and meeting compliance?
• Will it be able to help you organize documents and provide easy accessibility to all documents (old and new)?
• Can updates to a segment of a document be carried through to other associated documents?
• Can alerts be set up to aid in communicating security issues, tracking updates, releases, or even new documents?
• If your organization is global, will all the documentation be done in the US or will some be written overseas? Is translation software available or will the local team manage their own documents? And if so, how are change or update notifications handled?
• Do you want to create an internal or web-based (an intranet) directory for each organization or product division and have it broken down into sub directories?
• Do you need a database-type tool or repository where files are indexed for faster retrieval?
• Do you need to set up a hierarchy or a content structure where the main product is on top and similar products below it with a documentation breakdown for each segment of the products? Each segment being anything from requirements, specifications, training, processes, procedures, marketing, etc.
• Do you need to work with mappings of documents or where documents link to associated documents?
• Finally, how much can you afford and what do you expect on your return on investment?

Set up a plan as to what you want the CMS tool to do for you and decide if it is the right fit for the organization. Also, is the tool you need user friendly enough, helpful, and will you be able to train others on it? No matter which tool you eventually decide on (either purchased, developed, or open source), make sure you have at least a uniform style guide for each division to use for consistency and clarity in writing, formatting and styling. This is especially relevant for global companies. Make sure your organization has the right tool or necessary processes set up to be able to answer ‘yes’ to the above questions.

If you have any suggestions or other ideas, please leave a comment.

Part of a Technical Writers job is to create test plans and to communicate it to the Quality Assurance Team. The Technical Writer will be responsible for the standard test plan (see previous posts) for user acceptance testing to be performed, maintenance of an organized list of open issues, verification of resolved issues, and continuous communication with all stakeholders. Many Technical Writers can gather information and create test plans from working and collaborating with relevant stakeholders, managers, clients, etc. But with the popularity and reliance of mobile devices being a huge part of our industry now, how do we create independent test plans for applications loaded onto them? What should be in these quality check blueprints?

Similar to application testing on a laptop or personal computer, the test plan will involve equipment, functionality, user acceptance testing, interface, data entry, validity, and regression testing. But this is not enough. The standard testing is not just the application any longer. It will also involve content (such as size, language, security), DRM (Digital Rights Management), data risks, the device location, mobile carriers, special features (i.e., screen orientation – rotational ability, voice activation, screen navigation, etc.), audio, the cloud, social media access, simultaneous application behavior, and as usual, various scenarios.

Compatibility

• Will it be able to coexist with other applications?
• Will it work without interference or interruption if, e.g., a message or a call is received?
• Will it work within any device and with any system version?
• Will it work with any mobile carrier?

Functionality

• Will it work on touch-screen devices?
• Will it provide user friendly functionality, e.g., scanning images?
• Will it provide eye-pleasing displays, movement, and presentations?
• Will it provide quick keys, menus?
• Will it provide accurate swiping capabilities?
• Will it be able to function via wireless technologies, i.e., Bluetooth, WiFi, etc.?
• Will it function even when coexisting with the maximum uploading and downloading of various applications?
• Will it be able to upload or download material and objects, i.e., revised content or images files?
• Will it be able to download all or any entertainment items via the application links if needed, i.e., e book material, games, movies, etc. without conflict?

Consequences

• What are the effects of haste in jumping from one module or application to another?
• What are the results of service disruption?
• What are the outcomes of moving incompatible objects from one module to another?
• What are the effects on battery power usage?
• What are the effects of program errors on other applications?

Testing mobile device applications is quite challenging as you are not working off of a network nor have access to any normal desktop features such as viewing via a large screen, nor be able to manipulate any hardware or software. You are solely dependent on your mobile carrier (i.e., cell phone carrier) and your mobile device.

Testing therefore can be difficult. I do not have any experience in using specific testing tools to help as I have only tested my practical needs in determining whether or not a mobile device application works for me or not. But if you are familiar with some mobile application testing tools, please leave a comment.

Definition – Policies and Procedures involve ensuring control over processes, giving directions, setting standards and following them. In other words, maintaining compliance or preserving requirements. The Policies are a set of rules or guidelines that are decided upon by higher-ups. The Procedures are the steps or processes involved in completing a task. Policies and Procedures:

• are a growing necessity in Companies as they aid in ensuring accuracy, consistency, upholding standards, and
• usually answer questions of who, what, and how.

Companies are paying more attention to compliance due to concerned awareness of risk management, security, confidentiality, etc. From protocols and regulation material to process breakdowns, companies are now having more Technical Writers create Policies and Procedures documents.

Industry Usage – You need Policies and Procedures for laws, guidance, audits, performance improvement, training, sales and marketing, instructional designers, medical writers, etc.

Below is a sample list of areas in organizations using Policies and Procedures:

• Healthcare – in elderly care (for appointments, lab procedures, admission/release process, equipment usage, emergency care, insurance, etc.)
• Business – in insurance (for processing claims, liabilities, appraisals, reinsurance, etc.)
• HR – in orientation of new hires (for employee handbooks, training, etc.)
• Education – in learning (for equipment handling, libraries, labs, instruction material, etc.)
• Manufacturing – in production (for safety procedures, setting routines, monitoring schedules, quality checks, etc.)
• Technology – in applications (for setting development standards, designing new software, authenticating privileged users, testing systems, data management, etc.)

As shown above, Policies and Procedures help eliminate confusion by reducing questions and errors, clarify instructions, and maintain smooth operations by keeping stakeholders all on the same page.

Writing – Creating Policies and Procedures is not an easy task. It involves a lot of research and verification. Begin by creating an outline for yourself as to who needs to be interviewed and observed and what needs to be researched. For Policies and Procedures to work, keep it up-to-date. In the end, they have to be for the target audience and be user-friendly. Follow many of the rules mentioned in previous posts to make your document understandable and clear. Most importantly make sure the higher-ups support the creation of Policies and Procedures. Also, interview the right resources, such as your SME (Subject Matter Expert).

Questions to ask:

• what (does the policy or procedure do, what is expected, acceptable, and what is not.),
• why (is it done this way, does it have a history, etc.),
• where (is this policy or procedure performed, under what circumstances, etc.),
• when (does this policy or procedure occur, etc.),
• how (is this policy or procedure prepared, completed, etc.), and
• who (is responsible for ensuring the success of the Policies and Procedures, who is affected or is involved, etc.).

Organization – Organize the Policies and Procedures so that they are all located in one central database or location and is easily accessible to the right personnel. Categorize them for easier access. Create a process to maintain communication on all levels so that you can track changes and apply updates accordingly.

If you have thoughts to add, please leave a comment.

How much is too much? How do we know how to present a technical document?- Whether it is written for projects, systems, communication, procedures, applications, prototypes, education, training, user guide, specifications, or updates, etc., how do we know how to design the material for the target audience? There may already be a style guide, but what if you think it is outdated and the guide needs to be revamped and needs a fresher approach? You can use the following few ideas as suggestions, when involving the design of certain documents.

Many people have examined or looked into how to design material for easier comprehension. Sample tests have been run to understand how a user perceives what they see in images, figures, pictures, symbols, charts, diagrams, etc. You have to be able to describe – how, why, what, when, where, and results. I think the best approach is to use practical examples. If you are writing about complicated tasks, break them down.

There is nothing wrong with having diagrams or flow charts with sub-diagrams or sub-flow charts. There are a lot of existing diagrams and templates online where a main diagram is presented as the upper image, followed by two other sub-diagrams located below it.

Think of a hierarchy or a triangle. All of this can be presented on one page. You can have a frame of information located above two other frames of data. This presentation makes it more interesting and appealing to the reader. Not only that, it will present a more understandable representation of what you are trying to describe, especially when working with anything technical.

People like to see variety in order to remember certain aspects of a diagram. If you can, make it simple and fun. Sometimes, for complicated descriptions, you need a sizable diagram to explain a model. For these situations, I think it is appealing if you break up a page filled with diagrams followed by a page of bullet-ed text. But you have to be sure that they are on facing pages or else you might lose the flow of the explanation.

And sometimes, for briefing meetings, you can just draw a simple diagram by hand. As an example, when creating a presentation for a marketing meeting where the attendees need to know only the major concept of a product, you can just include simple drawn out models and views of the new product.

Technical Writers are involved in many areas of a business (as writers, designers, trainers, analysts, etc.), so they need to know and understand the mind of the audience and be aware of their strengths and weaknesses and create a document accordingly. This way, the document is a valuable asset and won’t just be thrown into the corner. As another example, for procedural or use-case designs, make sure the instructions display what to do next. Use arrows, shapes, or any kind of configuration to make the image stick in the readers mind.

If you have other ideas about designing or including designs for explanations, please leave a comment.

Functional Specifications (based on the Requirement Specifications) describe how something works; what the user will see, what the application will offer, what the finished product will present. The Functional Specifications are written for the manager/supervisor, describing how the application works based on the Requirements document.

The Functional Specifications (usually created after the Technical Specifications) can be simultaneously created close to the time when the product is almost ready for QA, depending on general practices. Why? Near completion time, the Technical Writer will have a detailed understanding of the finished product and be aware of all the functional changes that occurred during the project life cycle. By that time, the document will be able to describe how the product will function, operate, and behave. In essence, the Functional Specifications will show how the product now truly works.

It’s not just how it works- it describes how it flows. It will state how one function or activity will present another segment or slice of a product. The Functional Specifications are like mappings which lead you from one section to another. It illustrates or describes the logical flow during a process or procedure.

It is not a User’s Manual where you are told to click on an icon, tab, or item to be given a screen shot or image of the outcome.

The Functional Specifications have to:

• provide if needed, a description of company policies and possibly contact information (depending on the number of company sites),
• contain a brief introduction highlighting features,
• include a getting started section describing the system structure, or an applications menu description (i.e., what tool bars will be presented ), and its relevant functions,
• provide error messages,
• detail how-to- instructions or procedures, explanations, and activities,( i.e., tabbing leading to what outcome),
• provide instructions for accessing help , a glossary ,and an appendix with a samples section if needed,
• indicate what activities cannot be done,
• how sections, procedures are broken up; the logistics involved,
• how one process leads to another,
• describe the circumstances as to when certain events occur or not occur,
• supply the detailed information for each section and include screen shots, images or process flows, and
• lastly, provide an evaluation form if desired.

Functional Specifications also show the history by:

• explaining the deviations from the original Requirements Specifications,
• explaining the decision to include or not to include an item in the final product,
• clarifying why certain decisions were made,
• describing the environment, and
• noting the SME’s, Developers, Manages involved.

Functional Specifications will be presented via:

• videos,
• documented instructions,
• mappings,
• in-person training, or
• training tutorials.

The individual creating the Functional Specifications should be the same individual presenting the Technical Specifications because they are the most knowledgeable about the workings inside and out. In the end, the document like all documents, must speak to the target audience. For Functional Specifications, you have to write to several audiences; make sure you are familiar with all of them before writing. This way, you will know what to emphasize within the document.

This is the second part of the post ‘Getting To Know Your Technical Writing Department’. We have read what questions need to be asked regarding Projects, Writing, and Collaboration. Now we need to see how documents are reviewed, stored, what tools are used to produce the documentation, how the works are distributed and how we can make improvements.

Review – Define the review process

· Are there style guides they follow and who maintains it
· Is there a standard logo for each document?
· Who reviews their work
· Who edits their work
· How are changes reviewed
· Is there a process for reviewing, editing, and rewriting
· Estimate the turnaround time for each new revised work
· Who tests out the documents for accuracy (note by individuals, department, and project)
· How do you get feedback from users (clients, developers, SMEs, customer service, etc.,)
· How do you get feedback from content on the web

Storage – Keeping track of the documents

· Where and how are the documents stored
· Is there a schema where all legacy documents are kept
· Is there a methodology that is followed to stay organized, or is there an existing content management system that maintains new and revised documents
· Where are confidential documents stored?
· Do we index or tag our documents
· Are any processes automated

Tools – Our tool sets

· What tools do they use to produce their documentation
· Get a break down of what tools each writer uses and their expertise in them
· What tools would they like to have
· Are some of the current tools that are too challenging for some

Distribution – Distributing the documents

· Is there a process in place for distributing completed and revised documents
· Who gets the newly completed documents and how many are produced and who takes care of that process

Global – Standardizing it all

· Who are the global contacts
· How do we virtually connect with them
· Is there a process in place for ensuring that all documentation standards are met
· Where are all the terms defined so that we are all on the same page for terminology
· How are files exchanged
· How are updates made

Improvement – Empathize with your writers

· Do they have any ideas for improvement
· Do they feel overworked
· Are they writing for more than one project at a time
· How long have they worked as technical writer on particular tasks
· Do they feel stagnant and would they like to switch gears and write for some other projects

When you have reviewed all this information (I know it’s quite a lot), and have analyzed your mapping or matrix, you will be able to make adjustments where necessary. Pinpoint where your strengths and weaknesses are. As with documentation, make sure everything you need to know about the department is standardized, controlled, and structured. All this work will help you get a clearer picture of your departments’ Technical Writers functions, the departments’ performance, and where improvements are needed.

What happens when your new job is to manage or reinvent a Documentation Department? Where do you begin? What do you need to know? Here are some tips on getting to know your Department and Technical Writers without stepping on any toes and without being too forceful. There is a lot to talk about here, so this is the first of two posts. Even two posts may not be enough, but I will share what I can for now. Let’s begin.

During the first meeting with the Technical Writers and team members, let them know why the meeting was called and present your ideas of what makes a viable Documentation Department and simultaneously, gather the following information from each member of the meeting. You can ask the following questions (if the group is small), hand out questions at the meeting (and arrange a follow-up meeting), or email the questions prior to the meeting (if the group is large or global).

By getting to understand the current processes, you familiarize yourself with the team members and you can determine whether or not changes have to be made.

Projects – What projects are the technical writers involved with?

• Are we included on project plans or charters?
• Do the writers also create their own project plans?
• Who sets the writers deadlines?
• Are more than one writer assigned per project?
• What projects have they worked on?
• Estimate how many documents are needed for each project.

Writing – What is involved?

• What documents are each writer in charge of?
• Do they write mostly for content or the web?
• What format are most documents produced in (docx, pdf, html, xml, etc.) ?
• What departments and whom do they meet with for gathering their information?
• How often do they meet with others and are they helpful?
• Is it difficult to set up meetings with Subject matter Experts (SME’s) to get the needed information?
• Estimate the turnaround time for each new document created.
• What happens when a document is late?

Collaboration – How well is the department working with others or vice versa?

• What meetings do the writers attend for gathering information?
• Are they part of status meetings?
• Are they given enough time to produce their documentation?
• Do they attend meetings when a project begins?
• How are they notified of changes/updates to documents?
• How are they handling conflicts or bottlenecks?
• Are they given enough time to make necessary changes to their documents because of a change in process or development or any kind of adjustment that impacts the document?
• What road blocks or bottle necks do you face daily?- such as – Delays about notification changes or when there is too long of a lag in time between reviews.

When you have gathered all this information, create a mapping or matrix for yourself and try to see the whole picture of how the current Documentation Department operates. See if there are trends or cycles of heavy and light workloads or when more resources are needed. This should help you get a clearer picture of your Technical Writers functions, the Department performance, and where improvements are needed.

We are all always learning and thinking. I came across a new expression and/or synonym for Standard Operating Procedures (SOPs) that Technical Writers create that I was not familiar with. It’s called Work Instructions (WI) or Job Instructions (JI), and I thought I would give a short post on this newly discovered item.

In a previous post, I described SOPs as procedures that are defined on a higher level. It is a set of approved guidelines consisting of procedures or processes that have to be followed from beginning to end. Having an SOP standardizes tasks and eliminates confusion about performing tasks or functions. They provide instructions on what has to be done. But the processes that are to be followed are sometimes called Work or Job Instructions.

I think I can clarify Work/Job Instructions as directions that provide detailed step-by-step functions/tasks that have to be accomplished. Work/Job Instructions are the sub parts of the Standard Operating Procedures.

Here’s a simple example: How do you start a car?

The SOP states that to start a car, you first have to turn on the engine. You must first take the key and insert it into the car, followed by placing your foot on the brake and taking it out of park. The WI/JI, on the other hand, will tell you to insert the key, and with the key between your thumb and forefinger, twist the key forward till you hear the engine rev up. It will also advice you not to take the key out. Then the next detailed steps will be listed.

Hence, the WI (JI) spells out or outlines each procedure within an SOP and as with any procedure, be sure you include the following items:

Purpose –the overview and reason behind this process, the objective or goal, and expected result.

Resources – the individuals responsible for particular tasks (i.e., project manager, developer, marketing, tester, staff assistants, etc.) including whom to notify, etc.

Procedure –the steps and the list of items needed to complete the task (i.e., equipment, files, tools, security, visual aids, etc.)

Make use of SOPs and WIs (JIs) as they are necessary to ensure standardization and consistancy of a company’s best practices and solutions. By creating and applying these documents, there will be a reduction in time and effort, misunderstandings, risks, and of course a decrease in cost for the organization.

And as always, both the Standard Operating Procedures and the Work/Job Instructions ensure quality work and that is what is important. Note: – there are currently a bunch of tools available to assist in creating Work Instructions as well as Job Instructions. These tools include training as well as templates to assist you in creating the documents. Research and investigate them to find a suitable one for you.

In the previous post, I talked about focusing on some of the more fundamental and helpful components of a document (charts, figures, images, flowcharts, pictures) and their usage. My next favorite tool along this line of usage is the application of tables. Using tables for simplifying the presentation of data provides a comprehensive arrangement of a structure, outline, pattern or order of what is being focused on. It is a great presentation tool and visual aid for comparisons, breakdowns, lists, functions and descriptions.

Tables come in all sorts of sizes and shapes. You can highlight specific headings or columns or rows or even highlight diagonal sections or even just certain individual cells of a table. Think of a tic-tac-toe game for highlighting cells to distinguish relevant elements.

As an example, use this particular form of highlighting when you have a table denoting products features versus competitors’ features. You can show similarities of a product vs. dissimilarities by highlighting just those cells containing items you want to point out like pricing of one vs. another. Usage of this type of table is great for marketing or creating a proposal depicting, e.g., the pros and cons of a product or project.

Tables are noted for data display and also for their ease of use and flexibility for allowing the inclusion of graphic charts (pie, bar, scatter, etc.) to reemphasize or to give anther representation of what is in the table for further clarification.

Tables can also be created with separated but adjacent columns to present a more visual appealing look. By using your imagination, you can have tables in the form of tables within table cells or figures, text boxes, or even images within table cells. This is really useful if you wanted to for example, put borders around certain portions of text located within a cell for emphasis.

You can also create your own table styles, e.g., you can insert columns and then select borders and select dashes, or zigzags for vertical break points. Just use your imagination and create your very own unique tables. The zigzagged portion of the table could be used to show what is to be eliminated or cut off from a product. You can color portions of cells for emphasis to give it more weight or prominence.

There are many things you can do using a table. We are surrounded by table designs; look at the periodic table filled with our chemical makeup. When working with data structures, table sets are automatically created using embedded tables. When we impart descriptions, we use table formatting for our columns and rows. Use them whenever you can. Design and shape the tables any way you wish. You can shape them in the form of alphabets or some similarity to reinforce something you might be teaching.

Tables will help you present the information in a user-friendly way and keep you organized. It will take patience to create the table style you want to use or, you can just apply any pre-formatted table and customize it to what you need. They are worth applying to your documents.