On the Job

Question: What’s all the fuss about wikis? Aren’t they just a glorified Web site?

Answer: On a wiki, you or another approved team member can change text, change a number, change a photo RIGHT NOW.
Let me tell you how that has to happen on a non-wiki site.
Since 1993, when I built my first www.techwriters.com Web site, I have to:

Build a very time-consuming e-mail specifying exactly, and very clearly the changes I want Send it to a Webmaster I employ (if I can find one)

Then wait

Then ping him or her, forward the e-mail to him or her again, Did you get this? When do you think you might have time to do this?

One such supposed Webmaster was an employee who told me he builds Web sites and updates them for customers, like a Realtor in town. But if the text was in a table, like my prices for my vacation rentals, he couldn’t do it. And he only wanted to recruit. It took him WEEKS to get around to making Web site changes for me, when he could do it, knowledge-wise.

Web sites have become much more complicated than HTML, which I did teach myself. I have graphics on my three sites (www.Techwriters.com; www.SeasideHome.US; www.SantaCruzHome.US ), I have prices in tables, I have forms that take money. Way beyond my employees’ knowledge or my HTML knowledge, and the knowledge of most Web site companies. I only recently found a guy who can do CSS, PHP, and the requisite CMS for my sites. He’s $85/hr. I do know of one good programmer; we’re lining up more. Now they must know Ajax, Python, and Joombla.

I just migrated my three sites off the got.net ISP here in Santa Cruz and onto GoDaddy, which supports PHP5, which the ISP must support so that I can turn all of my sites into wikis. I can’t wait to have wikis instead of what I’ve got now—very expensive, time-consuming, and maddening to change.

So yes, I like wikis—for many reasons.
If you want one, go to www.WikiSolutions.biz

Question: This place where I'm working has very bad management! They're always changing their minds about what they want me to do. I've been here two months and they've had two reorganizations. Nobody seems to know what they're doing. What should I do?

Answer: Write some good user instructions for the most important product this company offers to customers. Ignore everything that goes on around you. Take our on-line course to learn how to write superb manuals.

Question: How can I keep my project (writing the Help for the new release) on track when nobody here, including the manager, knows anything about technical publications and what I need (feedback from the programmers, more information, no more changes to the product user interface)?

Answer: You're about to learn why you get the big bucks. You have to make a plan and a schedule. Include important milestones you need to complete, and by what date. Get JoAnn Hackos' book Managing Your Documentation Projects, published by John Wiley and Sons. Read this entire book. The author tells you what to tell your manager and the engineers so that they will respect you.

Question: I’m new to technical writing, and I must estimate how long it will take me to write a user guide they need for a new product. How do I determine how long it will take?

Answer:

1.	First, find out these details about the product you must document: • Who uses it? • What things can they do with it? • Why do they need it? • Where and when do they use it? • For what purpose? • What can they do after they buy it that they couldn’t do without it?
2.	If your user guide explains software, find out from the Product Manager, the Project Manager, and the developers everything users can do with the software.
3.	Make a complete list of everything the software helps users accomplish tasks.
4.	Make an outline, put features of most value to the user at the top.
5.	Use the outline for a preliminary table of contents.
6.	Next, you must take at least a week to look at and experiment with the software. If the Company does not have an Alpha or Beta version of the software you can look at, it’s too early for you to start creating instructions.
7.	Write a documentation plan. As a technical writer, you get management approval for this plan before you start to write. The doc plan includes: • A profile of the typical user, or customer, including his or her age, education, job title, level of technical knowledge, and typical tasks they must do in the course of their daily job • A sample page showing how your instructions will appear on the screen • If your guide explains hardware, include the time and resources necessary for professional illustrations • A table of contents • A preliminary index, with typical entries you will include • A list of people in the company who must review your chapter drafts, for technical accuracy • A schedule, stating when you will complete the first three chapters, the next three, and so on. Include in the schedule: time for proofreading and correcting, time for technical reviews, for editing by a professional editor,final production and release.

When you have completed a doc plan, you know how many months this project requires. We only have space in this FAQ to summarize what you do to plan for a user guide. In our on-line training course, 'How to Do Technical Writing', we provide you detailed information for planning and writing user guides.

Question: I am considering taking your technical writing course, since it looks good, and I started this job with absolutely no idea of how to do technical writing other than frantically visiting the Microsoft and Sun sites and reviewing their help documentation. I was a copywriter/magazine article writer before, although I had done a few white papers.
Is it normal for one person to be asked to:

1.	Write all software documentation for the company
2.	Do all copywriting
3.	Create all marketing handouts for tech shows such as Gartner (24 of them in six weeks, to be exact)
4.	Edit all developer's project updates to customers since they don't speak English as their first language
5.	Create all database developer's documents
6.	Create all user documentation including online help manuals
7.	Create all business gap analyses for clients
8.	Create all Web content for all client web sites and email creatives
9.	Create company proposals (and by great luck having the company win 100% over the past two months, so being asked to do even more for clients now, who are winning proposals too and asking for more...you get the idea)
10.	Write all corporate communications policies, and teach them to staff engineers/developers
11.	Gather specifications for projects from new clients once company is awarded a project
12.	Be a client project manager, to interface with the development team members and act as a liaison with clients

Answer: I'll take this hideous list of tasks they lay on you and tell you what, normally, tech writers can reasonably deliver.

1.	Write all software documentation for the company. Yes, that's your job.
2.	Do all copywriting. NO. They have to hire a marketing communications writer from Webster Techwriters!
3.	Create all marketing handouts for tech shows such as Gartner (24 of them in six weeks, to be exact). NO. They have to hire a marketing communications writer.
4.	Edit all developers project updates to customers since they don't speak English as their first language. NO.
5.	Create all database developers documents. ABSOLUTELY NOT.
6.	Create all user documentation including online Help manuals. Yes, that's your job.
7.	Create all business gap analyses for clients. ABSOLUTELY NOT.
8.	Create all Web content for all client Web sites and email creatives. NO. They have to hire a marketing communications writer.
9.	Create company proposals (and by great luck having the company win 100% over the past two months, so being asked to do even more for clients now, who are winning proposals too and asking for more...you get the idea). NO. They hire a proposal writer.
10.	Write all corporate communications policies, and teach them to staff engineers/developers. NO. Someone from HR has to do that.
11.	Gather specifications for projects from new clients once company is awarded a project. NO. The Salesperson, who gets the commission does this.
12.	Be a client project manager, to interface with the development team members and act as a liaison with clients. NO. The Salesperson does this.

Question: What do they mean by an administrator's guide? How do I write an administrator's guide?

Answer: Administrators work in IT (Information Technology) departments at companies. They have the job of keeping the network, e-mail, telephone system, servers and mainframes up and running, 24/7. Consider Visa. If their computer system goes down, merchants everywhere can't process purchases. Or think of a bank. If their software or network goes down, the ATM machines don't work.

System Administrators install and fix servers, network equipment such as routers, and large switches that process thousands of phone calls. To do their job--keep very complex systems up and running--they refer to manuals that, ideally, tell them exactly and accurately what to do.

To write a sys admin guide, you have to put yourself in the sys admin's shoes, figure out what he or she will need help with, then give them clear directions, in numbered steps. You have to build an index they can go to, to quickly find the particular Help they need. Obviously, you have use the software or equipment yourself to become very familiar with it. Don't forget to test the steps you give them!

To learn how to write a system administrator's guide, we recommend that you take our course, 'How to Do Tech Writing.' In the course, offered right here on this Web site, you learn what to write, how to write it, and how to present it so that a sys admin can find what he or she needs, and follow your instructions.