Browsing articles in "Blog"

Check Out Our New Office for Technical Writing In the Philippines!

Jul 8, 2015   //   by Barry Saiff   //   Blog, Uncategorized  //  No Comments

 

Technical Writing in the Philippines Just Got Serious…

June 15, 2015 marks the day Saiff Solutions claimed its new writing pad in Tagaytay, Philippines. And we’re loving it here!

As part of a shared building, this office runs roughly 33 square meters and provides just what we need to deliver technical writing in the Philippines. See what our Technical Writer Gaile thinks of our new office.

This think tank allows our talented content development team to deliver the best value in technical writing for our clients. And we’re excited at filling our office with more global talent, as we are expanding!

Have a look at our office in the pictures below:


Croydon1_n

Click on a thumbnail to expand

As you can see, we are still organizing things and settling in. Meet the Board of Directors.

Global Content Collaboration: Making it Work

Jun 9, 2015   //   by Barry Saiff   //   Blog, Content Strategy, How-To, Managing Technical Writers, Outsourcing, Reference Articles  //  No Comments

How widely dispersed, geographically speaking, is your content development team? Or, are you currently in one location and considering expanding to another?

Implementing a global content collaboration strategy can be a rewarding investment. Making it work begins with understanding these key success factors

  1. What Country?

Which country best fits your needs? Consider these factors to start:

  • Cost and availability of skilled labor
  • Language
  • Infrastructure – electricity, Internet, transportation

In considering countries, don’t leave out the Philippines –  the #1 rated country for business English.

  1. Ensuring Success and Quality via Project Management and Editing

Let’s face it, splitting your content development across countries, if not managed properly, can multiply your problems instead of reducing them. You need competent project management, in each location, to effectively facilitate global collaboration. The pitfalls of no project management include misunderstood instructions, missed deadlines, and poor quality work.

Editing, for grammar and substance, is a crucial part of quality control. A lack of editing is the chief culprit in many failed projects.

To prevent misunderstandings and build rapport, qualified editors should work in the same physical location as writers. Working with a writer in-house can accelerate progress dramatically, especially if English is not the writer’s first language. Body language, eye contact, visual cues — all of these support effective communication.

A less desirable option is to use local editors to work remotely with offshore writers. This is far better than not having any editing at all.

  1. Choosing a Low-risk, High Reward Pilot Project

For your first project, choose something that has clear scope, goals, and instructions.

Updating existing documentation, reworking documentation for a new platform, converting files to new formats — all of these can make good initial projects. By choosing a simpler project, you can minimize the number of variables, and better determine what is and is not working.

  1. Managing Risks

Act on these risks early to mitigate future mishaps.

  • Meetings Across Time Zones

While business needs sometimes dictate odd hours, allowing people to work reasonably normal hours most of the time has great rewards. Many projects only require odd hours for regular meetings.

Some of the things to consider when scheduling meeting times and work hours are:

– Availability of transportation: In many places, no transportation is available between the hours of 10 pm and 5 am, for example.

– Health: Night shifts are not for everyone, and may not be healthy for anyone on a long-term basis.

– Opportunity: Time zone differences may allow you to get more work done in each 24-hour period.

  • Work with Multiple Communication Styles

The keys to successfully working across cultures are awareness, relationships, and inclusion.

A lack of cultural awareness can cause many problems. For example, in some cultures, “Yes” doesn’t always mean “Yes.” Quick conversations that lack substance can lead to misunderstandings that surface later, after damage is already done.

Ask questions, frequently. Clarify everything. Surrender the idea that your culture is better or more effective – there is no cheese down that road.

Effective communication occurs within effective relationships that are based on inclusion. Diverse communication channels can help build a strong, collaborative, multinational team. Include multiple avenues for connection and learning, for example:

  • Shared wiki sites/intranets
  • One-on-one meetings via videoconference or phone
  • Group email lists
  • File storage/sharing sites
  • Occasional conferences with the entire project team or subgroups

Global content collaboration can be an enriching experience for all involved. Faster turnaround, lower budgets, and higher quality are all possible.

Are you considering outsourcing content development? Saiff Solutions, Inc. can help you develop a strategy to succeed. Contact us if you’d like to talk: barrysaiff@saiffsolutions.com

We have a free offer until July 7, 2015.

Welcome, New Year!

Saiff Solutions, Inc. wishes all of our followers and supporters a Happy New Year and a prosperous and joyous 2015!

Once again we are sharing with you our year end/year start questions. Use them as you see fit, to empower yourself, your organizations, and your loved ones.

Questions and Answers – 2014/2015

1. What did you accomplish in 2014 that you want to be acknowledged for?

1a. How well did you perform on your intentions and promises for 2014?
Question 5 – completion steps
Question 6 – vision for the year
Question 7 – Intentions to learn
Question 9 – greatest challenges
Question B – Promises for 2014

2. What did you learn in 2014? (LESSONS LEARNED)

3. What did you fail to accomplish in 2014?

4. What is still incomplete for you? Consider your answers above, as well as people, events, or situations that you may be incomplete with.

5. Are you willing to let it go? If not what do you need to do in order to get complete? By when will you do that?

6. What is your vision for 12/31/15? Name at least 3 things.

7. What do you intend to learn in 2015?

8. What are you grateful for?

9. What is your greatest challenge?

10. What support do you need?

Optional bonus questions:
A. Fill in the blanks: I am willing to give up _______________ in order to have _________

B. What are you willing to promise for 2015?

C. What requests do you need to make to get started on fulfilling your promises and your vision?

Why Do We Need Good Technical Writers?

Mar 12, 2014   //   by Barry Saiff   //   Blog, Reference Articles  //  1 Comment

And what do technical writers do, anyway?

Have you ever asked, or been asked why you need good technical writers?

The answer:
Developing quality documentation that effectively addresses the needs of each user, without overwhelming them with information they don’t need, is a skill that takes years to develop. It differs fundamentally from other forms of writing used in marketing, engineering, testing, or product management.

Penny-wise and Pound Foolish?

In a real-life example at a large company, the IT Team needed to make an immediate change to the VPN (Virtual Private Network) login procedure. This change would affect thousands of employees who logged in daily. To save precious time and money, the IT Manager asked an IT Engineer to write an email explaining the new login procedure, instead of using the Documentation Team.

Do you agree with the IT Manager’s decision? The result suggests it was not the best approach: The Helpdesk Team received over 10,000 support calls from employees who had problems logging in, ultimately costing the company thousands of dollars in technical support time.

The IT Manager learned some fundamental truths:

  • Good product documentation reduces support costs.
  • Not all engineers are also good technical writers.
  • The cost of hiring a good technical writer in many cases pays for itself many times over.

What Do Technical Writers Do?

Let’s look at how a technical writer works. What does a technical writer do when faced with a new project? Here are five of the most basic steps.

Step 1: Learn about the product

The first step is to gather background about the project or product. What needs does this technology address? What is the purpose of the product?

Step 2: Identify Your Audiences

Who uses this product? What are their roles, education, and work experience? Make a list of your user types, for example:

  • User 1 – Database administrator: technical degree, manages databases.
  • User 2 – Loan officer: experienced computer user, finance professional, approves loans.
  • User 3 – Executive: computer user, focused on reporting features.

Step 3: Start Counting — Features

One thing a technical writer does at the start of a project is count. Two of the most important things to count are features and tasks.
To count features, consider:

  • How many pages does the user interface contain?
  • How many elements or controls on each page?
  • How many total elements, on all pages, menus, etc.?

You don’t need a complete list. Just make some initial notes, for example:

  • Main pages: 8
  • Sub-pages, dialog boxes: 11
  • Elements per main page: average 12
  • Elements per sub-page or dialog box: average 8

Total elements: 184

Step 4: Begin Task Analysis

What tasks must a user accomplish? Each task includes a list of steps. Each step is a single action. Start a list of tasks, for example:

  • Add borrower
  • Add loan source
  • Configure borrower options
  • Configure regions
  • Configure global options

Step 5: Putting it Together

Consider the users you identified. To complete these tasks, what will they need to know?

Good product documentation requires topics, or chunks of information, of at least three types: task, reference, and concept. For a description of each type, see http://saiffsolutions.com/home/topic-types.

You’ve made a good start. Answering these questions enables you to start answering others, such as:

  • How many task, reference, and concept topics do I need?
  • What information is important to each type of user?
  • How can I organize the documentation so that all users find what they need quickly?
  • How long will it take to complete the documentation?

What About Apps?

You may be thinking, “This seems like a lot of work! Is all this needed for two sentences to explain a mobile app?”

While some apps are very simple, others are not. A sentence or two may suffice for one page or function. A complex app will require quite a few sentences.

And, as Mark Twain said, “I didn’t have time to write a short letter, so I wrote a long one instead.”

Writing fewer words with equal effectiveness takes more skill and more time.

What is the Value of a Good Technical Writer?

Doing this type of analysis repeatedly enables a technical writer to notice things that even an engineer who developed the product may miss. Good technical writers have years of experience writing, rewriting, and then rewriting again to eliminate unnecessary words.

Why do we need good technical writers? Let us count the ways:

  • To create accurate, concise documentation that enables users to complete tasks independently.
  • To organize information so that users quickly find what they need.
  • To avoid confusing users with extraneous or out-of-place information.
  • To avoid losing users due to inappropriate assumptions about their knowledge and background.
  • To reduce support costs.
  • To increase customer satisfaction.
  • To demonstrate to customers that the guidance they need is accessible and easy to use.

Of course, as with every profession, there are both highly competent and less competent technical writers. At Saiff Solutions, we have decades of experience in hiring and managing outstanding technical writers. Because we are located in the Philippines, where English is the primary business language yet labor costs are much lower than in the U.S., we are able to offer the best value on the planet in technical writing services.

Is there something we can help you with?http://saiffsolutions.com/home/

Barry2014012c

Topic Types

Jan 6, 2012   //   by Barry Saiff   //   Blog, Concepts and Definitions, Reference Articles  //  No Comments

Hang on!  Before reading further, we just wanted you to know that this post is related to the previous.

Task Topics contain a procedure, represented by a list of numbered steps. The title of a task topic names the task. After the title, a few introductory sentences introduce the procedure by answering questions such as:

  • Why should I perform this task?
  • What do I need to do before performing this task?
  • What can I do after performing this task?
  • What problems might occur if I perform this task?

After the introductory material, a one-line lead-in introduces the procedure. A list of numbered steps follows. Each number is followed by only one sentence, which instructs the user to do something. Any additional material needed for that task is provided in a separate, indented paragraph under the numbered step. Some of these paragraphs can be links to other topics.

Here is an example of a task topic that explains how to write a task topic:

[Title] Writing a task topic

[Introduction]A task topic includes a procedure, consisting of a numbered list of steps. A limited amount of introductory material precedes the procedure. The procedure itself provides only the information essential for performing the task. In some cases, you can provide a link to relevant information, instead of cluttering up the procedure with reference or conceptual information.

[Lead-in] How to write a task topic:

  1. Write a title for the topic that includes a gerund (a word ending in “ing”), and describes the task documented.
  2. Write an introduction for the topic that explains the context of the task.  Mention any restrictions on performing the task.
  3. Write a lead-in sentence that begins with “How to” and matches the title.  End the lead-in sentence with a colon. The lead-in sentence is usually not a complete sentence (see example above).
  4. Write the numbered steps for the procedure.

The first paragraph of a numbered step contains only one sentence. That sentence instructs the reader to do something. Additional information is provided in separate paragraphs indented below the numbered paragraph. Keep the additional information minimal.

By not mixing, for example, task and concept information in the same topic, you gain several advantages:

  • A reader who just wants to know how to do a task does not need to wade through conceptual information to find the procedure she needs.
  • If you choose to present all the procedures together in a special document, you don’t need to separate out conceptual information.
  • You can easily provide all the task topics to the team that will test the procedural documentation.
  • By including links to the most relevant concept and reference topics in each task topic, you can direct the reader who is interested to useful information without cluttering up the procedure for the reader who doesn’t need that information.

Reference Topics contain reference material. Reference material may be necessary to perform tasks or to understand technology. Reference topics often contain tables of information. For example, lists of parameters and their corresponding values or impacts. A table of types of mortgages and the requirements for each type. A table of features, showing which features are available from the product’s graphical user interface (GUI), and which features are available from the command line interface.

Concept Topics provide background and explanation. Even if it is necessary for the reader to understand quite a bit of background information before performing a task, do not include all of the information in the task topic. Instead, include a link to one or more concept topics that provide the necessary background. For example, an explanation of each type of mortgage and its history belongs in a concept topic, not in the midst of a procedure for choosing the mortgage type.

Process Topics describe complex processes that consist of multiple tasks, each of which consists of multiple steps. A process topic typically contains a table. Each row in the table represents one task, and provides a link to that task topic.

Process topics can document any of the three basic types of processes:

  • Linear. In a linear process, a set number of tasks must be performed in a specific order, without variation.
  • Branching. A branching process contains one or more decision points. At each decision point the reader can choose from two or more “branches” or alternate paths through the process.
  • Circular. After completing a circular process, the user can continue to perform the same tasks again. Some circular processes can be started at any point in the circle.

The process topic shows the sequence of steps, and indicates any decision points where the sequence may branch, or become circular. A process topic may contain a flow diagram, that documents the process flow. Flow diagrams can be particularly useful for branching and circular processes.

Online Help Topics typically contain a table that lists controls, commands, or features of an interface or product. These topics are accessible from within the product interface. If the topic contains information specific to the interface location from which it is accessed, it is called a context-sensitive topic.

Context-sensitive help topics often list all the controls available on a specific page or screen of the user interface, documenting each control, and provide links to relevant task, concept, and reference topics. Depending on your content strategy, you may choose to also provide procedures in the online help topics themselves, rather than linking to task topics.

Information Typing

Dec 30, 2011   //   by Barry Saiff   //   Blog, Concepts and Definitions, How-To, Reference Articles  //  No Comments
OK, I understand that topic-based authoring is crucial to being able to reuse topics in different contexts, so that I can make available to each user the documentation they need on the device they use. What about topic types? Where do they fit in, and why do they matter?

Information typing provides the answer. Successful topic-based authoring depends on information typing. Each topic must have a type. The topic should only include information consistent with its topic type.

All topics share the following characteristics:

  1. The topic begins with a title that concisely described the information contained in the topic.
  2. The topic is stand-alone. That is, the topic can be understood without reference to other topics or documents.
  3. The topic contains references or links to other relevant topics.

Note that characteristics 2 and 3 are not contradictory. State-of-the-art product documentation has left behind the assumption that all readers will read every book in the order in which it is presented. If each topic stands alone and can be understood by itself, yet links to other relevant topics, the reader is empowered to choose the order in which he consumes the content. This is a more effective approach because many readers will pick and choose, even if they are instructed otherwise.
For product documentation, nearly all the information needed can be classified into one of the following basic topic types:

Two additional topic types are actually special types of reference topics:

Types of writing

Dec 19, 2011   //   by Barry Saiff   //   Blog, Concepts and Definitions, Reference Articles  //  1 Comment
What is Technical Writing?

What is technical writing? Common usage differs in different places and contexts. In some universities in the Philippines, courses that teach how to properly write business correspondence and reports are called technical writing courses. This usage differs from the definitions below.

Business writing includes all types of non-fiction writing that may be needed to support a business. However, business writing refers most often to business correspondence, both internal memos and business letters, and business presentations, reports, and similar documents. Business writing also includes marketing writing.

Technical writing is writing that deals with technical subject matter. This includes training materials and all types of product documentation. Technical writing often refers mainly to software documentation. While technical writing is a subset of business writing, technical writing can occur in non-business environments, such as universities, non-profits, and government agencies. Technical writing often includes marketing writing. Technical writing also includes various specialized types of writing, for example aerospace, medical, legal, and scientific writing.

Marketing writing includes any writing intended primarily to represent a product or an enterprise to its market. For example, brochures, data sheets, white papers, and Web sites.

Of course there is a good deal of overlap between these categories. Web sites often provide product documentation and other technical material. White papers may be more technical or more marketing-focused. A business proposal for a product may be full of details about the technology of the product.

Just in the USA, there are approximately 20,000 technical writers, of whom at least several thousand are writing software documentation. It is likely that many millions of other workers in the USA are engaged in business writing during at least part of their work days.

The definitions here are important because of the confusion between business writing and technical writing that appears to be prevalent in the Philippines, and perhaps in other countries as well.

Pages:«123456

Saiff Solutions In The Media

- TechWhirl
- Nominated for 2015 Rice Bowl Asean Start Up

Click image to enlarge

Testimonials

“Barry [Saiff] is one of those people that every company needs. He is a very efficient and productive member of any team and on top of that ensures that others feel a member of the team also. Whilst at Brightmail I got to know Barry as he was the organizer for our local toastmasters group. His energy and enthusiam encouraged this collection of diverse people to create a wonderful group experience. I would recommend Barry for any position that required trust, loyalty and a great sense of humor.”

Raj Rana
Sr Systems Engineer, Brightmail
December 27, 2010

Read more testimonials here.