Technical Writer Q & A

OpenProj - The Project Management Tool

2012-02-07T18:05:00.000-08:00

OpenProj is an open-source desktop project management application similar to Microsoft Project. OpenProj has a familiar user interface. This can be used to manage projects of varying size and type. The posts that follow are intended as guides for those who want to learn how to use this project management tool. OpenProj is an open source product from Serena Software Inc.

How to Select a Tool for Documentation

2011-11-28T10:37:00.000-08:00

Selecting the right tool for your new documentation project is vital to the successful completion of the project. It will avoid lot of trouble later during the project.

Selecting the tool depends on various factors such as

Audience
Media used
Purpose
Whether online collaboration is required or not
Ongoing update and maintenance
Cost factor
Expertise required to maintain the documentation

Given these factors, one would consider some of the following:
For online help that does not require online collaboration: Adobe Robohelp, ComponentOne DocToHelp, Madcap Flare, etc.
For printed documentation: MS Word, Adobe FrameMaker, XMetal, etc.
For online collaboration (e.g., when teams spread across continents need to contribute to documentation): WordPress, XWiki, SharePoint Wiki, etc.

This is not a complete list, but just a few that came to my mind. I will update this with a list of most commonly used tools in the market.

Writing a Technical Reference Manual

2011-11-28T10:10:00.000-08:00

Any technical writer creating a technical reference manual should ensure that (s)he has the following:
1. A sound understanding of how the project is structured
2. Complete knowledge of the control flow within and between all components
3. Complete knowledge of all the APIs in the application
4. Knowledge of the data structures and the storage containers used
5. Knowledge of the variables used in all the components
6. An understanding of how the installation files are packaged
7. An understanding of how the user interface has been developed
8. Knowledge of the variables that need to be configured to initialize the application
9. Sufficient knowledge of the software platform on which the application has been developed.

While the requirements specification and design documents usually contain this information too, an understanding of the reasons why, say,a particular API has a certain boundary value, or a certain variable is a configuration variable and not a runtime variable, would be invaluable to someone explaining their utility.

Welcome!

2011-11-27T19:53:00.000-08:00

Welcome to Technical Writers Q&A to share knowledge on your field of expertise. We have huge amount of knowledge lying in each of us. There are new or experienced technical writers who are looking for answers to their questions. Most of the time time, we work solo or sometimes in a group, but the extent of our reach to the technical communicators community is limited. That's why this forum comes into existence. I would come back here every time I have a question. While I gain some knowledge from here, I would also see if I could help anybody by answering their question.

So, this blog is dedicated to the technical writers community to which I belong.