Document Hack (A Technical Writer’s Journal): Document Mismanagement System

I have mentioned Documentum in this space before. Documentum is a useful, though certainly not perfect, document management system. Documentum stores files of all sorts, from graphics and desktop publishing files to applications under development. Once a file is stored in Documentum, individual users can “check out” that file (like checking a book out of a library). When they check out a file, it is then locked within Documentum. That means others cannot check the file out although they can download a copy of the file.

Locking prevents more than one person from working on the same file at the same time. This is important because if two people make different changes to the same file, then they essentially create two different files. Merging those two files back together can be a nightmare. Requiring people to check in and check out files prevents duplication of effort and lost changes.
One of the other handy aspects of Documentum is that it stores each version of a file that has been checked in. Because of this, if a major problem occurs, people can always go back to a previous version of the file. This helps prevent disasters.

Documentum allows people to copy files. This means that an individual can download a copy of the file without checking out the file. This is also handy because people often need to view or use files, but they do not need to change them. For example, a manager could download the latest version of a project tracking spreadsheet and bring it to a meeting without checking it out. Because of this, a programmer working on the project can still make updates when they finish parts of the project. If the manager checked out the file, no one on the project team would be able to update it and project tracking would come to a halt.
Documentum works fairly well. There are occasional bugs, but none as bad as a typical Microsoft product. The problem with Documentum is that human beings are allowed to use it. Human beings will screw up a system every time.

That was the case last week on my project. The new lead writer, without telling the rest of us, copied all of the project files to her hard drive to work on them. She did not check them out; she just copied them, not expecting any of the rest of us to work on the files but not telling us not to. I then came along, and in my ignorance, began copyediting the files. I did this the correct way. I checked out the files, worked on them, then checked them back in. After three days of this, our lead writer realized that I had altered about half of the files she had been working on.

On the plus side, the writer understood it was her mistake and took the blame. On the minus side, three days worth of my work had to be dumped. All of this could have been prevented if the system had been followed. It is not my intention to blame the other writer unfairly. If I had taken the time to tell her what I was planning on copyediting the files, she would have had the chance to tell me what she had done, but I trusted the system, and the work was lost because it relies on humans to follow its system.

This is not the only time that I have run into problems with the human element of Documentum. One of the typical problems is what I call file hoarding. This happens when someone checks out a file and keeps it for days or even weeks. This obviously causes a problem because it keeps others from working on a file, but it also causes a bigger problem. The key to using Documentum properly is to check files in every time there is a significant update to the file. That provides an easy path backwards for people when things go wrong. The greater the gap between backups of a file, they greater the amount of work a single error or crash can destroy.

The company policy here is that Documentum files should be checked in at least once a day, even if they are immediately checked out again. Daily use of Documentum lessens the problems associated with computer crashes and file corruption. When people hoard files, they tend not to check them in at all. They just keep the file on their hard drive. If they at least checked the file in once a day and then immediately checked it out again, disasters could be averted. The company I am currently contracting for has a series of policies regarding the use of Documentum. Unfortunately, there is no path for enforcing these policies. Violations are not merely tolerated, they are completely unacknowledged.

Because of this, problems like last week’s lost work are not just possible, they are inevitable. The keys to any system or process working are as follows:

1. The actual system must be well planned and workable.
2. The people within that system must be properly trained.
3. The policies needed for that system to function properly must be enforced.

In this case, the system itself is workable, but there is a limited amount of training and almost no policy enforcement. Because of this, accidents like last week happen on a fairly frequent basis.

Poetry Writing Tips Explained: Tip Three

Say what you want to say and let your readers decide what it means.

Most beginning poets spend too much time thinking about the intentions or themes of their poems. There are many different approaches to writing poetry. Some poets write highly structured poems. Some poets write poems about very specific subjects and have definitive goals about what they want their poem to do. While these approaches can produce great poems, I do not recommend them for beginning poets.

Young poets and those writing poetry for the first time often become frustrated because they cannot seem to say what they want to say. Many experienced poets have the same problem. Self-expression is not an easy task. The task becomes even harder when you start out with very specific goals or constraints. Writing a great sonnet is not easy. Writing a great villanelle is even harder. That does not mean you should not try, but do not expect immediate success and do not constrain yourself even further by deciding in advance exactly what to say.

You can sit down with a topic in mind. If you want to write about a certain landscape or situation, use that as a starting point. If it does not work, however, do not force it. Sometimes the poem you really want to write is sitting in the back of your mind, waiting for you to get out of its way.

This may seem to be the antithesis of the advice at the top of the page, but it must to be said before we can discuss the meat of my statement, which is that you need to feel free to write exactly what is on your mind. If you want to write about basset hounds or aluminum cans, you should write about them and say what you have to say. You may create a great poem or you may not. Not every poem you write will be great. No one writes perfectly. Even Shakespeare had off days.

Sometimes a poem will shift topics as you write it. Follow the new direction. The new direction may end up fitting your original theme in a way you did not expect, or you may decide to discard the first part of your poem to make way for the new thoughts. You may even find that the first part was right after all and what follows does not work. Whatever the situation, follow the direction a poem takes. You can always rewrite later.

Do not get trapped by worrying about whether a poem “makes sense”. If, when you finish, the poem feels right to you, then you have done what you needed to do. Feel satisfied with that. If you do not like the way the poem turned out, either rewrite it or write another poem. Do not expect perfection with every attempt.

At some point, if you are brave enough to let the world see your poems, you will discover that your readers do not recognize all the themes you intended for your poem and all the points you tried to make. They will also see things in your poem that you never intended. You need to accept that people can have different views about the same poem.

One of the great truths in creative writing is that a writer lacks the perspective to judge his or her own work. When you read your own poem, story, or any other piece of creative writing, you bring to it every thought that was in your head at the time you wrote it. When others read your work, they see the words on the page, not the thoughts you put behind the words. Your readers will also bring to your poem everything that is in their own head. Their interpretation of your poem can be valid, even if it does not agree with your interpretation.

Do not spend your time worrying about other people’s interpretations of your poetry. There will always be a difference between your intentions and other people’s interpretations. Say what you have to say. If people ask you what your poem means, feel free to tell them what was on your mind. If they try to tell you what they think your poem means, listen carefully. You do not have to agree with them, and you do not have to change anything about the way you write just because you think they got it wrong. Give their interpretation some thought and see if you think it is valid. If you do not, that is fine. Perspective is a wonderful thing. The more you have, the more you can use.

Poetry Writing Tips Explained: Tip Two

The bigger your point, the more important the details are.

Many poets choose to write poetry for political, social or philosophical reasons. These poets have a specific point-of-view that they want to express. There is nothing wrong with writing poetry to express a viewpoint, but I have found it often results in poetry I have no interest in reading.

I do not want to be told that the genocide in Sudan is deadly and awful. I already know that it is. I do not want to be told that child abuse is terrible and hurtful. I already know that it is. I know that war is terrible and I know that it is sometimes necessary. I know that people can be hurtful and they can be kind. Most people understand these things.

I am not telling you what you can or cannot choose as a subject. Write about Sudan. Write about child abuse. Write about war. Write about cruel people or happy people. I am willing to read a poem on just about any subject. The key is to focus on the details, not the general point. The poem will fly or plummet based on the details. If you want to tell a story about a war, focus on a single moment, person, or visual. Dig into the details of your subject.

I do not want to read a poem that tells me war is bad, but I might be interested in a poem about a truck that has survived a war — a poem that describes the dents, the scratches, the burn marks on the surface of the truck and how each mark got there. Those are the details of a poem. The point of a poem is usually expressed best when it goes unstated and readers draw their own conclusions.

The key is that no matter what the subject of a poem is, great or small, the goal of the poet should be to make every part of that poem as interesting to the reader as the subject is to the writer. Blanket statements can kill a poem. The same is true of overly obvious or overblown images. Often, when people think they are being dramatic, they are being melodramatic. This is another case of focusing on the subject rather than the details.

When developing an image, make it a goal to veer away from emotional descriptions and look for literal descriptions that match the emotion. Compare these two lines from my hypothetical war-torn truck poem.

The angry bullet hole was dark and frightening

An irregular circle burn surrounded a bullet hole close to the driver’s door

While I am not claiming either line is art, the first image aims for an emotional effect and (I think) fails. The second line keeps emotion from the overt description, but demonstrates the menace involved. I am not saying to keep emotion out of your poetry, just be mindful that your readers would rather feel something on their own than be told to feel something. That said, there is no doubt the second line carries emotion. The words burn and irregular evoke negative emotions and the location of the bullet demonstrates the possible consequences of the shot. The line is more subtle, but it still creates an emotional effect.

Writing a poem that sets out to express a particular idea or opinion is difficult and often unnecessary. You already have a point-of-view, and it will come out in your poetry. You do not have to set out to tell how you feel or what you want people to understand. If it is inside you, it will show up in your poetry. All you have to do is keep writing.

Poetry Writing Tips Explained: Tip One

A poem with Love in the title (or Destiny, Hate, or other HUGE themes) already has two strikes against it (and I like love poems).

One reason that people write poetry is because they have strong emotions that they want to release. That is a great reason to write! The problem is that a strong theme like love or hate has already had millions of poems written about it. Millions, in this case, is not an exaggeration. If you attempt to write a poem explaining love or another major emotion or theme, your will be walking a well-traveled path. It will be hard to distinguish yourself from what has come before you.

Robert Frost made the road less traveled a lasting metaphor, and in this case it applies perfectly to poetry. There is no reason not to write about love and hate and destiny. These fundamental human themes will stretch on long after we are gone. The key is to develop the theme in a way that has never been written before. This may sound daunting, but it is actually quite simple.

When you write poetry about a major theme, the roots of the poem should be in your experience. Tell your story. Love may be a difficult title for a poem, but The Way She Looked at Me Last Friday could easily be the title of a love poem I would want to read. The theme remains the same, but the path is more distinct.

I rarely set out to write a poem about a particular subject. I write what comes to me without planning. This is not the only way to write a poem. Many poets know exactly what they want to write about before they put anything on the page. My method, however, means that I almost never start with a title. Picking the title is generally my final task. In this way, I feel like I have a much better grasp on what the poem is about and how I want the title to reflect that.

To me, the title of a poem is like the door to a room. It is the first impression that you get, even before entering. It influences whatever comes after. Still, a large and forbidding door can lead to a comfortable room and a beautiful door can lead to a dungeon. Titles are the same way. A title can provide reinforcement or contrast. For an example, let me take the most overused poem in the history of poetry.

Roses are red
Violets are blue
Sugar is sweet
And so are you

Now go back and read the poem, but imagine it had one of the following titles:

To My Love

Things I Never Wanted to Say

The Last Thing She Read

Code Talker

Each different title transforms the poem. Yes, the poem still stinks, but the meaning of the words must now be considered in their new context. The poem’s attitude and theme change under the influence of the title. This is why a major theme should not be the focus of your title. If we stick with the metaphor of a title being like a door, then the title Love is a sixty-foot high shocking pink door covered in roses. It is going to be hard to create a room that can match a door like that.

In the end though, the choice of title is up to you. Charles Bukowski used Love in the title of a poem, but the full title, Love is a Dog from Hell, certainly knocked the roses off the door. If you think your poem lives up to the name, call it whatever you want.

Document Hack (A Technical Writer’s Journal): When a Project Ends

As I noted in my last entry, the project I have been working on is almost finished. My two accomplices and I are proofreading our two thousand pages of documentation and soon it will be out the door and so will I. This is the nature of contract employment. You spend the length of a project with a client and then you move on. You sometimes get lucky and manage to find another project with the same client (which I have already done twice here). If not, you look for work elsewhere.
When you leave a client, especially if you leave amicably, there are some things you should do:

Put Yourself Back On the Market
As soon as you know a project is nearing completion, you should start the process of looking for the next project. Update your resume. Make some phone calls. Get the ball rolling. For more information, read How to Find Technical Writing Jobs.

Make a Contacts List
The people you work for, and with, at a company can come in handy later. You may need them as references. You may want to ask them a question about a technical issue. You may want them to send you a copy of the documentation when it comes out. You never know what you will want in the future and it is good to be prepared. I am terrible with names and in cases where I did not make a contact list I have had a hard time finding the information I needed.

Make a Copy of the Documentation You Worked On
Unless your employer specifically instructs you not to keep a copy of the documentation, you should make sure to get a copy for your portfolio. In most cases, you can simply put the documents on a CD-ROM, a jump disk, or e-mail them. Whenever possible, get electronic copies. Electronic copies will allow you more options than print copies. If you can, get both electronic and print copies.

Thank People
It is a good idea to thank the people you have worked with, and to do it in writing. Give them thank you cards or write a short email. Always include your phone number and/or email address so that they can contact you in the future. People sometimes have questions even months after you have moved on. More importantly, having your contact information makes it easy for clients to find you if they want to give you more work.

Clean Out Your Desk and Your Computer
People generally remember to take the personal items from their desk, but they often forget to take the ones on their computer. If you have any personal files on the computer, save a copy and then erase the files. You do not want your employer reading old love letters when they are looking for your documentation.

Celebrate
When a project ends, it can be a little scary, but you should always remember that the successful completion of a project is a great accomplishment. Take the time to celebrate.

How and Why to Start Your Own Print or Web Zine

By Bob Sassone

If I was forced to pick the one aspect of my early writing career that I felt was most important to my success and progression as a writer, it wouldn’t be my work on my college paper, or the work I did for my local community newspaper, and it wouldn’t even be getting my own weekly column in a newspaper chain when I was only 22. It wouldn’t even be getting a sales job at a top music magazine, and sneaking in some writing for special editions and the company newsletter.

No, the smartest thing I did early on in my writing career was to start my OWN magazine. Why do I say this, when I didn’t get paid for it, I had to handle the tedious business end of things, and ended up spending a ton of money? For several reasons…

A BASE TO WORK FROM

When I started my music zine in early 1990, I had a few freelance writing credits and a stint in sales/research at a top music mag under my belt, but nothing really major that screamed “writer!” Creating and editing my own zine changed all that. It no only got my name and my writing out to editors and readers, it gave me a base to work from. Now I wasn’t just another writer trying to break into a writing career, having his clips and resume lumped into the 100 others sitting on an editors desk. I was an EDITOR and ENTREPRENEUR from his OWN MAGAZINE, with a business card, letterhead, a subscription base, employees, and a good product. This makes you stand out more. Get their attention, THEN wow them with your writing.

YOU’LL MAKE CONTACTS EASIER AND FASTER

When you head your own zine, you’re an instant “insider,” able to talk with other editors and publishers without being afraid they don’t have time for “some writer.” Of course, it helps to send a copy of your zine to them first, or the URL to your web zine. Just make sure the product is good before you let them see it. That makes the follow-up call easier.

ACCESS TO PLACES YOU WOULDN’T USUALLY GET INTO

When I started my music zine, I sent out press releases and media kits to a ton of music labels, record stores, and other magazines (this was in the days before the Internet, though my art director did have a cute little 2600 modem on top of his Mac to dial into the local college). I could not believe the response I got. Now, obviously, the record biz is different from what you probably want to do (the promotion departments are really eager to get their bands heard and interviewed), but if you send out press releases to the right people, you’ll become known, and you’ll probably get invited to events, parties, get-togethers, maybe even a concert or two. It all ties into that old clich� of networking. Get to know people who share the same interests as you do or can help you in your career and you’ll be better off.

And you’ll be amazed at what having your own zine can get you. My music zine got me into concerts for free and got me a ton of free CDs. My TV zine, which started out as a print-only zine then switched to web-only for the last year, not only got me in contact with other TV critics, it led to a job at a major newspaper, writing about television, and to my current job as editor for a TV web site.

IF YOU’RE GONNA WRITE FOR FREE, WHY NOT WRITE FOR YOURSELF?

There’s no way around it: when you are starting out, you are going to have to write for free. We all go through it. You have to build up your clips some how, and you do it by writing for your high school paper, your college paper, and interning at a local newspaper or maybe a magazine while you’re in college. And now with the Web, there are many places to showcase your writing, but be warned that most of them do not pay, especially if you are an unknown writer.

So, if you’re gonna write for free, why not start your own zine and write for free for that? Not to the exclusion of all other writing (which might get you better exposure), but as an addition to that. The more you write, the better writer you are. Besides, with your own zine, you control the topic, the style, and the length. And you just might be able to sell some of the articles from your zine to other print and web zines (though here’s a tip: if you try to sell an article to a publication, and the article has already run somewhere else, don’t put it up on your web site. A web or print zine might not want to run it if it’s already been available for free on the web already).

PRINT COSTS

Are you just doing a nice little personal zine to give to friends, a few subscribers, and maybe editors who want to see your clips? Then go with a Xeroxed zine, either 8 1/2 x 11 stapled in the corner, or a smaller digest size folded and stapled. Today, with so many publishing software programs available and print costs coming down, you can get professional, clean copies made at a good price. If it’s your first zine, don’t do what I do: I went with heavy stock, glossy paper, and had photos too. Thank God for those free CDs I got in the mail (shhhhhh…). Advertising helped too, but if and when I do another zine, I’m going the cheaper route. Look into the many print and web options that are available.

ADVERTISING

Obviously, the easiest way to pay for a print zine is to accept advertising, but it’s not always easy. You have to convince potential advertisers that the zine will be seen by enough potential customers. And if you’re doing your own little zine, with a print run of less than 1,000, this might be hard to do. The best bet is to go with local companies that might buy more than one month of advertising. But advertising, whether it’s on your personal zine or web zine, might be something you are not interested in. Not only from the aesthetic standpoint, but you also are of the mindset that you just want to get your writing out into the world and advertising is not only unnecessary, it’s distracting and too much work. If you are attempting to create a professional magazine though, with a large print run, subscribers, newsstand sales, etc, then you should at least think about advertising to help with the costs (especially if you go with color and/or glossy or want to pay your contributors).

PROMOTION

Keep people abreast of what’s going on by setting up an e-mail list through one of the list groups, such as egroups (http://www.egroups.com) or Topica (http://www.topica.com). And don’t forget the old-fashioned way too: printing out flyers, mailing out press releases, and getting on the phone to target people who might be interested in your zine.

GETTING OTHER WRITERS/STAFF

I had 4 or 5 people (who just happened to be my roommates plus the girl my best friend was dating) help me with the zine for free. Yours will probably do the same thing, especially if you give them a byline, free reign on what they write about, copies of the zine, some free stuff like CDs or magazines or a six-pack of beer once in a while. The good thing about zines is that if you’re a writer interested in working hard for free, then your friends will want to as well. Remember to have some fun with it. Of course, if you want to do a zine that is just your writing, a staff is unnecessary.

WEB SITES:

Nowadays, getting your own web site is not only easy, it’s becoming an almost necessary component of being a writer in the 21st century. And what a great promotional tool! Money-saving and time-saving. You can get a web site through many local and national ISPs. You can buy handy web-site making software (such as PageMill) that make web-site creating seem less daunting. You keep all the pages on the hard drive of your computer, and upload them to your ISP, who “hosts” your site. Of course, you might have to pay for this service. Though many ISPs give you a certain amount of space for a web site included in their monthly dial-up cost.

There are also many excellent sites that will not only host your site for free, but also give you all the free tools to create the site. These include Tripod (http://www.tripod.com), Angelfire (http://www.angelfire.com), Xoom (http://www.xoom.com). Just be careful of the wording on some of the contracts. Some sites actually have contracts that say that they own the content you put on your site! GeoCities got in trouble for this and was forced to change their wording.

As for domain names, it’s easy to get one. Either make it “nameofmagazine.com” or perhaps “yourlastname.com.” Tripod and other sites will actually handle the registration of a domain name for you, if you don’t want to use the usually longer URL that you get when you sign up for these free sites. Either way is fine, though your own domain name will be easier for readers to remember.

MAKING MONEY WHILE PURSUING YOUR WRITING CAREER

I went through a bad, depressing time when I thought that to be a “real” writer, I had to do it full-time, and if that meant not having any food to eat (except maybe pasta or soup every night of the week), then so be it. Don’t fall into this trap. Who cares what type of job you get to pay the bills, as long as you keep writing? My mantra for several years was “support your writing until it can support you.” Just because you’re not doing writing full-time doesn’t mean you can’t “call yourself a writer.”

One note: if you do a web site, make sure you get hard copies of all your issues. And if you do a print zine, make sure you keep some issues for yourself, so you can look at them again, years later, when you are writing full-time, and you can say “this is how I started.” Showing people something that you and your friends have created is a fantastic feeling, and can really propel your writing career.

Bob Sassone currently writes for tvsquad.com

Next Page »