Documentation Strategies Info Café – Thoughts on Information Design and Delivery

Peer Review vs. Editorial Review – Very Different Animals

2008-07-29T13:52:00.001-04:00

As technical writers, we’re often subjected to reviews by peers and editors. Although many people tend to lump these together, the two concepts are quite different.

A true peer review exposes your work to the scrutiny of others who are experts in the field documented by your work. It’s not editing. Editing is done for clarity and to make sure the author stays within the scope of work.

A peer reviewer assesses content for its technical accuracy. An editor reviews a document for its adherence to a specification.

Editors may review a document to determine if it communicates its purpose effectively. They also determine if the document conforms to style guidelines, not only ensuring good grammar, punctuation and style, but also validating organization and conformance to internal policies.

Technical writers normally don’t develop content to promote their own point of view. They express information in terms of their sponsor’s point of view, and it should be edited with this in mind. It’s almost like ghost writing.

A peer review process is applied to an original work subject to interpretation. Showing such work to others who possess a similar scientific or technical background increases the probability that errors in the research, the assumption, or the data will be identified and addressed.

===== Marc DiGiuseppe, Senior Consultant, Documentation Strategies

The Fine Line of Process Documentation

2008-07-25T13:42:00.002-04:00

It’s likely that someday someone else will be doing the job you currently do today. They will thank you if you leave them a legacy of good process documentation. The person who will fill your void must learn how to do your job. That’s a tough process in itself because training people is often easier said than done.

The human mind tends to group tasks together once they are mastered. This can be a problem for someone learning the process for the first time. They must see each step individually, without your shortcuts, to fully understand what they need to do.

When you first start the documentation process you will be amazed at how many steps are in a simple daily procedure. Use something like filling in your time sheet as an example. You would think, “How would I explain filling in my time sheet?” Most likely your first answer would be a generic statement: I go to my computer, open up the file and fill it in. Though this statement is true, it is not the slightest bit helpful to someone who doesn’t already know where the file is located or how to fill out the form.

More information is needed. I sit down in my chair, breathe once, blink twice and use my right index finger to double click the right mouse button. More informative? Yes. Helpful? Not so much. When documenting a process one must find the “happy medium” between these two examples. You need to write something informative enough to help but not so detailed that it causes confusion.

When you are finished documenting the steps of the process you must then test them to make sure that what you have created is useful. To do this you need to find someone who doesn’t know anything about the process. Have them sit down with your document and see if they can complete the process. If they can complete it correctly and with minimal coaching, you have done a good job. If they cannot, not so good. All is not lost, however. Go back and revise the steps that caused the confusion. Try the test again, and if necessary repeat these steps until your test co-worker can complete the process with ease.

The main issue with process documentation is making it informative but concise. Write it so any average Joe can do your job. This is very important because the person who takes over your job will never be as smart as you, right?

===== Andrew Everett, Intern, Documentation Strategies

Authoring State vs. Federal RFPs: Different Strokes for Different Folks

2008-07-24T10:57:00.002-04:00

At Documentation Strategies, we’re often asked to write a “Request for Proposal” (or RFP as it is commonly called) for a State Agency intent on purchasing a particular service or technology. Recently, we’ve started getting into RFPs for agencies of the Federal Government. We’ve noticed that there are differences in the manner in which RFPs are developed and written on the State and Federal level.

The State is usually focused on acquiring requirements specific to the issuing agency prior to defining the RFP. In other words, they’re usually focused on their existing business process and the procurement effort is driven by its requirements. The State agencies like to manage the design-build strategy for any particular procurement identifying the unique characteristics of their business process and how they believe the prospective contractor should address their expectations. State agencies aren’t too concerned with the size of the competing vendor as much as they are interested in that vendor’s depth of experience specific to their unique business requirements.

The Federal Government operates on a much different scope and scale. Federal Government RFP format and composition is mandated by the Federal Acquisition Regulation (FAR). They are typically broken down into sections that are identified by letter. There are 13 categories listed “A” through “M” covering topics from the scope of work to the applicable evaluation process. Federal Agencies are gradually being reorganized under performance-management-driven governance policies and are more focused on finding standard industry-accepted solutions to their business process management problems. Very often RFPs will ask the vendor to suggest a better approach to doing business that conforms to “best practices.” Federal agencies are interested in the capacity and capability of the competing vendor to deliver solutions that are compliant with these best practices and industry standards. On large-scale projects they sometimes conduct a “phase 1 down-select” to determine who will be permitted to compete on the “phase 2 RFP.”

State agencies sometimes issue RFIs (Requests for Information) to help them determine who is really capable of addressing the specific requirements of the RFP under consideration. This approach is somewhat similar to the Federal Government’s “down-select” process. However, RFIs usually are solicited to help the agency subject matter experts bone up on what they can expect from the private sector in the way of solutions. Rarely are vendors excluded because of an RFI.

Another feature we’ve noticed in Federal RFP strategy is an emphasis on oral presentation. The Federal evaluators expect the prospective vendor to have a pronounced and apparent command of the subject matter and applicable expertise. This lets them know how much of a risk the vendor might be in getting the job done should they be selected. Though there is a great deal of emphasis on sharing the pie with small business, it is the large established vendors that normally enjoy success as the winner or “The Prime.” But the Federal Government has a creative and equitable solution to address capacity expectations. On very large RFPs, the Federal Government allows competing vendors and approved small businesses to “partner” with the Prime as a subcontractor. In this fashion, the agency can draw in the best from each vendor and enjoy advantages unique to small business.

======= Marc DiGiuseppe, Senior Consultant, Documentation Strategies

Everyone Needs an Editor

2008-07-02T16:42:00.003-04:00

"The chassis should move in and out smoothly. If it does not pull the unit out, depress the clip releases on each side and carefully remove the appliance from the rack."

"Once the appliance moves smoothly along the rails tighten all accessible screws"

These are recent tidbits from my file of ambiguous technical writing. Ponder this:

Is the chassis designed to pull the unit out?
Is it OK to leave unaccessible screws loose?

Hint: After you write it get someone to read it. Their interpretation may differ.

=== Jeff Klein, COO, Documentation Strategies

Droll Tech Writers Go High-Class

2008-07-01T12:01:00.002-04:00

Here's some of the DocStrats team who were in the office on Friday, June 27th for our Ugly Shirt Contest. From left to right, they are Jeff, Mary Leu, Adam, Ann, Slade, Marc, Andrew and Preetham. Luckily the camera lens did not break...

How Not to Get Hired at DocStrats

2008-06-25T16:31:00.003-04:00

We get several resumes each week from people wanting to become technical writers. A distressingly large percentage of these resumes hit the trash within five minutes of arrival. Why? Read on for some tips on how not to get hired at DocStrats:

1) Address your cover letter to “Whom It May Concern”. It’s much too difficult to check our website and give us a call to get the right person’s name.

2) Indicate that your most recent job ended in 2004 and don’t tell us why. After all, it’s up to us to determine if you’ve been sailing around the world, in prison, or just forgot where you work.

3) Stress lots of inappropriate experience. You’re the finest mattress salesperson in the world? Best of luck with your career.

4) Don’t proofread your resume. Don’t fix the typos or the poor grammar, and by all means continue confusing it’s with its and there with their. Catching these mistakes is up to Microsoft Word, not the author.

5) Embellish your credentials. How could we not hire a PhD and Attorney with sixty years’ experience designing nuclear missile systems while working at the State Department?

Got it?

====== Jeff Klein, COO, Documentation Strategies

Two Negatives Do Not Equal Workplace Positives

2007-11-13T16:24:00.001-05:00

Basic math – a negative plus a negative cannot equal a positive. Sometimes, depending on how large the negative is, it may take quite a few positives to break even. This idea applies equally well to workplace negativity.

Some negatives at work are actually a positive (i.e., constructive criticism). Constructive criticism is a positive if used for productive means. It helps the originator voice their disapproval or lack of support in a manner that allows people to respond in a positive, non-accusatory manner. Everyone can then work together to move forward with the positive goal of accomplishing the tasks involved. Although this is the ideal process, it isn't necessarily the way it happens.

Many factors create negativity in the workplace:

having a bad day
personal problems at home
lack of support from management
uncertainty of work/job stability
lack of respect
rumors
pessimists

Negativity exacts a price not only at the personnel level but can be very costly to the employer too. Employees whether directly or indirectly involved in the 'line of fire' may become depressed, feeling sick and leading to absences.

Employees avoid working with others as the dread of negative attitudes and confrontation looms. As employee attitudes fail, it's a certainty that the company will suffer. Clients will start to see a lack of quality, timeliness and customer service. In a world of client-related satisfaction, this is a recipe for failure.

Negativity in the workplace needs to be recognized and resolved by both employees and management. Employees need to know that negatives are addressed and then be encouraged to MOVE ON. Management needs to acknowledge negatives yet respond with openness by maintaining the communication lines and tools needed to reach a solution. Tools include meetings, seminars and counseling. One excellent source is the American Management Association: http://www.amanet.org/.

Susan Combs, Project Office Manager, Documentation Strategies, Inc.

What does Project Management have to do with Software Development?

2007-11-13T11:31:00.001-05:00

The development style of a software project has a huge impact on the way that the project is managed. Until now I have been a strict believer in Iteration, while Jeff is a die-hard Waterfall guy. Over the last few weeks I have had the opportunity to sit in on Jeff's Project Management class. Any project needs to be managed to increase its likelihood of success. However different development methods call for dramatically different ways to manage the project.

Since I co-teach a project-based course for software developers at RPI, this simple fact is going to change the way we present development strategies to our students. I have a large collection of software development, UML, and other related technology books. Jeff grabbed Effective Software Project Management by Robert J. Wysocki from the shelf and refers to it in the class. I started reading it to get more information about a segment of the class I am contributing to. Wysocki talks in great detail about the different development models. He makes it quite clear that each development model has its place in the world. Iterative development is very good for projects where the solution is not fully crystallized in the minds of the stakeholders and the developers. Waterfall methods of development are suited for projects where the goals and solutions are completely developed and are not likely to change.

In our class at RPI, we poo-poo Waterfall methods as being risky as there is no feedback from the customer and testing. Using a waterfall methodiology an extended period of time can go by before the software being developed undergoes any kind of assessment for viability. When the developed software is evaluated, it may or may not do what it is supposed to do. If it fails its tests, lots of effort and resources, already spent, could be wasted. Using iterative development methods, you can have those results much sooner and that potential loss can be minimized.

Jeff argues that iterative methods are repetitive and wasteful of effort. The customer must have much more involvement in the development cycle and could potentially hold up the works if they don't respond in a timely fashion. (Experience shows that this is more common than we would like to think.) If a customer is not diligent about their response and their inspection the same result is easily possible. Near the end of the development cycle the customer could decide that the project is not really going in the direction they wanted and didn't realize this until now (because they hadn't been paying close enough attention).

In an email I received from Wysocki he told me that his book is the first step in developing a new discipline that combines software development life cycle and project management life cycle. Stay tuned for more developments about this emerging technology that could change the way we do things into the future.

John Sturman, Senior Consultant Documentation Strategies, Inc.

The future is here and it’s spelled DITA

2007-10-29T11:56:00.001-04:00

If you are considering moving to an XML implementation of your content, DITA is the way to go whether or not you're using a Content Management System. When I first started playing with structured content, I had a dilemma as to whether to move toward DITA or DocBook. DITA is proving to be the winner of this contest. DITA is not just a DTD or XML schema in which to provide information; it is a true architecture that allows for unlimited extensibility. That said, extending a DITA implementation is not that simple, but to a seasoned XML jockey, not hard at all. It requires creating some new XML that inherits from a piece of the existing DTD. Once the extension is created properly, it fits right into the architecture and should work with the existing tools.

Both DITA and DocBook have wide adoption and lots of already developed tools and processes. DITA is quickly being adopted by more and more mainstream applications. The most prominent evidence of this is Adobe Framemaker. Framemaker has become a real XML WYSIWYG editor, allowing users to edit DITA topics without having to convert back and forth between file formats. The latest version wraps a full DITA implementation, allowing users to develop DITA topics and maps using a familiar and powerful interface. Other applications which have adopted DITA include XMetal, Arbortext Author, and several Content Management Systems, like SiberLogic, and Vasont, and Astoria.

John Sturman, Senior Consultant Documentation Strategies, Inc.

Hello? Is Anybody Listening?

2007-10-26T17:10:00.001-04:00

Communications happens on a consistent basis throughout much of our waking hours. For as 'natural' as communicating can be, why is it that in when communicating should be happening the most, we seem to stall in the middle of the road?

Especially in the world of business, every type of communication has an outcome within the work environment. Whether it is done as part of the normal work day or is enveloped into a small to large project, poor communications can impact the success of a project, as well as the parties involved.

Proper, solid communication is the foundation of any good business. How a company communicates with other companies, customers and their staff will have a direct impact on the successes or failures. In today's world of information technology, pretty much any type of communication can be used and re-used in a variety of ways.

A few different ways of purporting good business communication are:

Establish communication plan(s) as necessary business-wide or project-wide.
Educate employees in communication techniques and protocols.
Use a variety of tools. Putting all your eggs in one basket may leave you with an empty basket.
Would you rather do business with a company that is progressive and flexible or one that has tunnel vision and is outdated?

Today, many businesses use the Internet for communicating. Even though electronic communications is considered state-of-the-art communication, it can also be a challenge to make it work positively and effectively because of the lack of body language in the communication. The receiver of the communication can only make interpretations based on the words alone. On the other hand, when written with professionalism, expertise and proper business etiquette, it can be a very successful tool.

Not all communication is written so don't forget body language! Body language works like a 2-way street. Your body language in conveying your information will weigh heavily on the listeners' approval or disapproval of what you are trying to accomplish. In the same respect, watch your audience as your speak. Are they alert and responsive to what you are saying? Are they yawning and rolling their eyes, playing with their pen or drawing pictures on a piece of paper? Remember to pay attention to yourself as well as your audience.

Business communication will only be as good as Management allows it to be. This can only be done by leading by example. Management needs to provide the communications plan, provide the tools, educate all parties involved and keep in mind that good communication will be only as good as the investment that is made into it on a continuous basis.

Susan Combs, Project Office Manager, Documentation Strategies

A Content Management System is only as good as the organization implementing it

2007-10-26T16:54:00.001-04:00

I recently attended the DocTrain East conference. Writers, managers, localizers, and vendors converged on Lowell, MA for this four day event. At DocTrain, people from all parts of the tech writing world come together to discuss and learn about technologies and methods relevant to their industry. One of the most important lessons I learned is that people play a greater role in a successful Content Management System project than the technology used.

"What Content Management System should we adopt?" is a regular question that many documentation organizations ask. This is a simple question with no simple answer. There are many Content Management System vendors, but more importantly, every organization has different needs and ways of working. It quickly becomes clear that choosing a vendor should be one of the last decisions made in the long process of adopting a system. As one of the presenters said, "it's not a how-to but a who-to". In other words, it's not what system you're using but who is using the system. You can have the best Content Management System but if people are resistant to the process you'll end with up with disaster. At the same time you can give a mediocre system to a dedicated group of people and be very successful.

John Sturman, Senior Consultant, Documentation Strategies

Relationships - the key to successful selling

2007-09-10T08:51:00.000-04:00

I started my career selling Dot matrix printers to businesses around a small town in South India, where I grew up. Selling wasn’t easy then and doesn’t seem any easier now. To succeed in selling you need a killer product or brand or both. Without a sustainable competitive niche there are rarely any distinguishing factors either with products or services. If there is a distinguishing factor it gets thinner and thinner every day.

Given this seemingly bleak outlook, I believe one of the many ways to succeed in selling is the relationships one has built over the years. Here are few tips to develop and maintain relationships:

Maintain a Rolodex and go over it at least once a year
Re-establish contacts you’ve had in the past
Participate in local networking events
Invite to lunch people you want to do business with

Finally, identify client needs and follow up quickly to win their business. Whether you manufacture a product, develop software applications or provide a service, do your due diligence first and then follow up on a regular basis.

Happy selling!

-- Preetham Morkonda, Project Services Director, Documentation Strategies Inc.

Projects are like Plutonium: compress them too much and they blow up

2007-09-04T16:50:00.000-04:00

Today’s Dilbert cartoon makes fun of project compression. The pointy-haired boss has a 300 man-day project and has just hired 300 people to complete it in one day. He’s telling them they will be fired tomorrow after the project is done.

Aside from the comment on modern high-tech employment (hire and fire, over and over), this strip reminded me of a famous quote from The Mythical Man Month, Fred Brooks’ tongue-in-cheek analysis of the fallacies of project compression. In the book, Brooks made the point that nine women cannot make a baby in one month, no matter how well managed they are.

As a long-time project manager, I am forever reminding clients of the 9-month rule. Every time you add a body, you geometrically increase interfaces. These interfaces (speaking, listening, reading, writing, and most of all, understanding) are human and by definition imperfect. At some point, and usually pretty early in the process, compressing a project timeline by adding bodies increases confusion and often makes things worse.

Good project managers spend a lot of time managing expectations. When establishing timelines and resource loading, don’t forget to plan for the inevitable requests for project compression. Determine what tasks can be parallelized, find places (usually back-end reporting) where extra bodies won’t gum up the works, and always, always manage user expectations politely but firmly.

--- Jeff Klein, COO, Documentation Strategies Inc.

Do You To-Do? I Do

2007-08-29T15:19:00.000-04:00

Have trouble getting things done?

Does your to-do list just keep growing and growing?

Do you even have a to-do list?

I look at my desktop and I see things that have been building up over the past week: business cards, reference books, fax receipts, a network drawing, 743 legal pads and notebooks, and several proposals varying in thickness. It’s a microcosm of my job duties.

Emerging from the organized mess are two glorious sheets of paper that I would be lost without: my to-do lists.

Multi tasking is a necessity for most people, and tracking those tasks is even more of a necessity (if such a thing is possible).

I use two to-do lists. One tells me what absolutely has to get done today, and the other is for the week. My long term projects I keep on a very handy whiteboard.

While the Internet can often be a time waster, there are a number of sites with extremely helpful productivity hints. They feature productivity suggestions for your life and for your computer. I’ve listed some of my favorites below:

http://www.lifehacker.com – “Tips and downloads for getting things done”

http://www.43folders.com - “Productivity and time management tips”

http://www.zenhabits.net - “Simple productivity”

They feature useful and fun articles such as “How to Be Your Own Executive Assistant in 3 Easy Steps” and “Fight Morning Grogginess”

Enjoy!

--- Adam Geyer, Project Analyst, Documentation Strategies Inc.

Competing in a competitive worker’s market

2007-08-23T16:49:00.000-04:00

Truly the hardest thing to do in today’s IT employment market is being competitive. The process of reaching the monetary goal that most Information Technology employees have set for themselves can sometimes be very tough; however, it doesn’t have to be impossible.

A large portion of today’s working IT class is unwilling to take a pay-cut to get a good job. It’s definitely unreasonable for most of us to take more than a 30% cut to be competitive but it’s SMART to find out what the market is offering and make yourself a little less expensive to be competitive against other prospective employees who aren’t even open to a $5 reduction in their consulting rate.

Employers are becoming EXTREMELY choosy and critical of those who come knocking their doors down for work and it’s quite understandable. Other than you, ‘the consultant’ providing important & necessary services for your employers, employers have a lot to offer even if you’re working as a C2C in a consulting engagement.

The most important thing to realize about today’s market is that the number of jobs available pale in comparison to the number of prospective employees looking for work. So next time a recruiter speaks to you about a ceiling rate take those words seriously and make yourself available for a little less to get that job.

--- Mel Aly, IT Recruiter, Documentation Strategies, Inc.

Keeping up with SarBox Documentation Requirements

2007-08-23T10:48:00.000-04:00

I’ve been thinking about Sox and the question “What is the single most challenging Sarbanes-Oxley issue today?

Search the internet, go to seminars, and speak with auditors. The impact that Sox is making on big and small public companies is profound. Studies report that small cap public companies ($100M or less in revenues), which in July 2007 were required to meet compliance with Section 404, are spending an average of 1.3% of their revenues to meet compliance requirements.

It doesn’t matter whether you’re big or small, as the Act does not make any distinction between sizes in its compliance requirements. To adhere to Sox’s requirements, it costs money.

Companies on average are expending thousands of staffing hours to meet just Sec. 404 compliance, which results in millions of dollars in G & A expenses.

While established companies strive to meet compliance deadlines and new companies rush to achieve initial compliance, most companies are faced with the intricacies of SOX.

Examining documentation generated by Sarbanes-Oxley efforts, most companies are asking themselves several questions: Are our processes well designed? Automated? Efficient & effective? How can we minimize this expense?

As an accountant in the private sector for over twenty years I ask myself what I would do to implement compliance.

Automated content management for current and archived documentation in key areas like transaction records, financial reporting, auditing, IT securities and internal controls would be a priority. Costs and complexity would be reduced, internal controls would be strengthened and integrity levels increased. The possibility of human error, lost documents or fraud would be minimized.

With increasing in-house staffing costs and professional expenses (auditing and legal) the key is to maintain compliance with the least impact on the bottom line. It’s not a question of how much you’re willing to spend, but how you can minimize what you HAVE to spend. Would I outsource? Maybe some or ALL? The answer may be yes. More about that in a future post.

--- Bridget Chandler, Controller, Documentation Strategies

I don’t have time to read, but I can listen

2007-08-20T16:52:00.000-04:00

I have the good fortune to live far from the maddening crowd.

However, I then need to drive pretty far to get to my job. While I am on my long drive I want that time to be productive and the radio only gets me so far. I have a long backlog of technical and job-related books and papers to read but don’t have time during the day. There are podcasts of all sorts, but I go through these too quickly for them to fill all that time.

My wish is the availability of technical books as recorded speech. They don’t have to be read by fabulous readers; a computer would do just fine. I am currently reading three different technical books when I have a spare minute. How about if I could get these books in a format that could be uploaded to my IPod? Then I would have a greater choice of how I spend my time in the car.

I know the technology is readily available and somewhat ubiquitous. My latest version of Acrobat (8.0) has the capability to read anything I highlight. Publishers could easily create these files for customers. How about a system where if I buy the book I can also get a sound file of the text from a publisher? All they would need to do is run a voice synthesis engine across the text of the book and make the resulting file available to anyone who can prove they own the book! I know there are issues to be resolved, but it would not be difficult.

The implementation of this service would get my attention and I would be more apt to buy books from publishers offering this service than from publishers that don’t. C’mon O’Reilly, how about it?

John Sturman, Senior Consultant, Documentation Strategies, Inc.

Technical Writing

2007-08-10T19:03:00.000-04:00

In creative writing, reality can be defined using any parameters in any pattern. In technical writing, reality results from the parameters. The greatest disservice done to software is the belief that the language describing and explaining its concepts has to be dry to be accurate, dull to be understandable. Software applications are better understood through careful, judicious use of rhetorical language: metaphors, similes, and mechanical techniques such as white space, bullets and intuitive graphics. Appealing to the user's figurative mind through language does not diminish his or her ability to grasp a complex concept.

To present complex ideas, we need quality communication. Software drives much of our businesses, yet what makes an application stand out from the many? Ease of use.
Software must be used before an ROI is realized. Training, guides, and references are the gateways to understanding and appreciating software. A well-written manual makes a software product more user-friendly, and saves technical support time. Crafted training opens software potential. Documentation and training are silent sale representatives.

The writer’s job through training and documentation is to make the client successful. The writer’s work is more than documenting or explaining, it is collaboration between people - an interdisciplinary approach. The writer must be mindful of the perspectives of each contributor, and inspire him or her to give the best information possible for the benefit of the user.

Technical writers best represent their companies as customer advocates and skilled translators.

Ron Milos
Techncial Writer
Documentation Strategies

Recruiting and relationships in today’s world

2007-08-09T10:05:00.000-04:00

Imagine you’re working at your desk and another employee stops by to pass on some upsetting news: There may be a mass layoff due to tight budget constraints.

You think to yourself I’ve been here a long time, my boss loves me and I always finish my work on time. I’ll be safe.

Later that week a couple of employees are called into the departmental manager’s office. After coming out they assure everyone that the manager only asked about the status of their current projects. The next day they both get let go due to “poor performance”. It could have been “budget reduction” or “business realignment” just as well.

In the current business environment, loyalty to employees is a thing of the past. People come and go, often with no good reason.

Once reality sets in some people wallow in despair, some relocate or retire, but many seek the assistance of professional recruiting firms.

Many recruiters will assure you that they have the best relationships with the clients they’re working with. They will mention all of the lunches they’ve shared and all their mutual friends. However, 85% of the time this isn’t the truth and unfortunately, they won’t be the ones suffering because of it. You will.

Make sure to do your homework on the recruiting firm you’re thinking about working with. Don’t be afraid to ask them about the business they’ve done with a particular client in the past, and always ask whether they meet with clients and consultants face-to-face.

Make sure to note who speaks with you about which clients. It’s also important to make sure that you’re not submitted to the same job by more than one firm because if you are, it could damage your chances of being hired. It helps to meet with the recruiting firm you are working with and maintain strong relationships with those you want to represent you.

In the end, a large portion of the recruiting firm’s success rate is about relationships - relationships with you, with the client, and with other vendors and local professional organizations. So before you run to that mega-firm that you thought could help you in an instant, consider working with smaller firms that value personal relationships. A strong bond between parties leads to continued success.

--- Mel Aly, Recruiter, Documentation Strategies Inc.

Cool Content Concepts

2007-08-07T14:00:00.000-04:00

I’m surrounded by people who template. This intimidates me – my comfort level sits somewhere between Notepad and Word, and I just threw out my Lotus 123 diskettes (5 inch…). So from my standpoint, content management was not something I was ready to embrace. Until now.

I realize there are lots of people who appreciate authoring environments and source control and all that HTML stuff, but not me. I’m usually too busy just trying to get my ideas down on paper. But even for me, content management systems have two compelling benefits I can appreciate and value:

The first is single sourcing: interchangeable pieces of content you can reuse over and over in many places. You only need to maintain content in one place. You know who changed it and where it gets published. And when you change it, everywhere it appears changes too (well, if you want it to). No more version confusion. No more out-of-whack documents.

The second benefit is multi-media publishing: my content is endpoint agnostic. Write something once and use it in manuals, white papers, web pages, online help and any other place it fits. Sure, some guy smarter than me has to build some templates, but once we get past that little bump everything zooms out with something only slightly more complicated than the push of a button. I love it.

The whole thing makes me want to learn about templates. Tomorrow.

--- Jeff Klein, COO, Documentation Strategies

AuthorIT -- My new best friend

2007-08-06T12:24:00.000-04:00

At Documentation Strategies we are always on the look out for technologies and tools that support the needs of our customers. AuthorIT continues to prove itself one of the great finds we have come across.

AuthorIT is an authoring environment, a content management system (CMS), and a publishing engine, all rolled up into one fully-integrated application. For those of you wanting your content to be a single source for many different output formats, this product is ideal. AuthorIT stores your content in small chunks that can be easily assembled into "books" and published to whatever format is called for. Output formats include Word, PDF, Web pages (either as HTML or XHTML), HTML Help, JavaHelp, Oracle Help, and WinHelp. You can also create standard XML and DITA from your content when working with other technologies. If you know the technology to which you are outputting, the formatting is quite simple as the application uses the underlying styles of the target format. For example, customizing your output to Word merely requires the creation of a Word template in the format you require. Using mappings in AuthorIT, output is automatically transformed into your desired look and feel.

I spent 12+ years as a FrameMaker die-hard and am quite used to going through the many steps needed to create the different output formats required by a typical technical writer. Creating my content in FrameMaker lets me take advantage of its robust editing environment, cross-reference features and formatting choices. From Framemaker I can print or create PDFs. If I want HTML, I can either use the built-in capabilities of Frame or, better, WebWorks Publisher. Once you get used to it, WebWorks does a fairly good job of HTML needs, including web pages and CHM, but you need to learn the interface and convoluted formatting language. Frame can now export as XML and even does a form of DITA.

However, this multi-application solution requires knowledge and mastery of different applications as well as the need to tweak and fiddle as the programs evolve. My new favorite tool is much easier to work with. From what I have seen of the new version of AuthorIT coming out soon, it's just going to get better and better.

---John Sturman, Senior Consultant, Documentation Strategies, Inc.

Wondering about SOX compliance? More about the Sarbanes-Oxley Act

2007-08-02T14:25:00.000-04:00

The Public Company Accounting Reform & Investor Protection Act is commonly called SOX or Sarbox. The Public Company Accounting Oversight Board is in-charge of overseeing and regulating compliance. Effective July 30, 2002, all public corporations are required to certify as SOX compliant.

Like any other regulation it should be addressed methodically, via proper analysis, documentation and study. Some sections of SOX are more pertinent to compliance then others.

To assist those seeking to meet the demands of this act, the following link is helpful: www.thecaq.aicpa.org/Resources/Sarbanes+Oxley.

SOX is arranged into eleven titles. One of the most important and challenging sections within these is 404.

Section 404 requires:

Companies must have the ability to sustain compliance.
Documentation structure with clear accountability.
Documented efficiency of operating and financial structure, procedures, and policies.
An enabling technology structure with IT securities.

Although this is quite a lot to deliver, there are ways your organization can successfully address the challenge presented by SOX.

Solutions

Form a compliance team.
Implement financial compliance processes.
Documentation/IT Consultants – Get support with expertise to identify your documentation or technology needs to help minimize non-compliance risks. They’ll do the work that a public accounting firm won’t do, such as preparing and implementing whitepapers and electronic documentation.

Not only are public companies required to comply but SOX is also hitting the private sector. Trends have found that one of four privately held businesses have voluntarily adopted some of the SOX practices. Why? To help create better companies: companies that invite both public and private investors, merger and acquisition prospects, and customers. Many private companies lack formal, documented controls, exposing them to unlimited risk.

One last reason to consider compliance: To limit their own risks, many lenders and insurance companies are applying more stringent certification requirements, like those of SOX, to privately held companies.

--- Bridget Chandler, Controller, Documentation Strategies, Inc.

Open Source Content Management - Researching Options

2007-07-30T09:58:00.000-04:00

Lately we have been exploring open source Content Management Systems. As we are in the process of updating our main website (www.docstrats.com) and need our own CMS support, we thought this would be a good opportunity to see what open source content management software is available and how capable it is.

After researching websites such as CMS Review, (www.cmsreview.com) and using another valuable website to test drive some of the packages (www.opensourcecms.com) we decided to give Alfresco a try. (dev.alfresco.com)

Alfresco is an open source Enterprise Content Management (ECM) system and as such is a bit more robust than the typical CMS, encompassing features like document management in addition to web content management. Although we were new to the open source world, we were able to set up an application server running Apache Tomcat and JDK SE 1.5.

We were impressed with Alfresco’s document workflow management process and the ease with which we could set up business rules. The collaborative features also worked very nicely. It’s very handy to be able to send a request to a co-worker for help on a document from within Alfresco.

Unfortunately, Alfresco is not yet rated to work on Vista and we ran into hardware compatibility issues when trying to access the server from our Vista-based desktops. We are looking forward to exploring more open source content management systems and we will keep you aware of our results!!

-- Adam Geyer, Project Analyst, Documentation Strategies

High profile women in business - Ann Moynihan profiled

2007-07-26T14:14:00.000-04:00

The President of Documentation Strategies, Ann Moynihan, was recently profiled in an article on women in business in the Albany-Colonie NY Chamber of Commerce magazine Visions.

The article can be seen at http://www.ac-chamber.org/pdf/visions_JUNE07.pdf

Content Management - a quick explanation

2007-07-26T13:59:00.001-04:00

For readers who need a quick summary of what content management is and why their boss or co-workers should care, we humbly present the following...

Content management enables organizations to reduce the amount of work necessary to create, edit and publish documentation of any kind. Content management stores content in one location yet enables it to be published in multiple formats to multiple locations. Content only needs to be created once, and updated in one spot, while formatting rules created and maintained by the user allow for it to be published in accordance with its end purpose. Content management also allows for pieces, or chunks, of content to be stored in a database and retrieved and added to a document when necessary. ‘Chunking’ allows for a great deal of reusability.

Content management systems often provide workflow process tracking so users can see whether a document has been created, edited or fact-checked. Check-in, check-out features enable all users to see if a document is being modified and by whom. This process lets staff spend more time generating value instead of reviewing tasks that have already been completed. Using content management less time is spent rewriting or re-editing older versions of documentation. Content management is capable of streamlining your documentation workflow from creation to publication.