Getting information
A large problem with bad documentation is that it does not answer readers' questions. To make sure that the user guides and the online help that we create are effective, we ask you many questions, so that we understand your software and how your customers use it.
Your time commitment
People in your team must prepare materials for us, answer our questions, discuss answers with other people in the team, and review drafts of documentation. For each day that TechScribe works on a project, budget for the following time (person-hours) from your team:
- For simple software that has no errors, one hour a day
- For complex software, four hours a day.
When we have a good knowledge of your software, we create detailed content for the software documentation. Your team must review this content carefully. The review step sometimes causes a delay to the delivery of the user documentation. Reviewing documents takes time. Sometimes, busy software developers do not think that a documentation review has high priority. Management must make sure that the documentation review is high on a software developer's task list.
What we ask you
At different stages of the documentation project, we have different types of questions. Typically, this is what you can expect:
- At the initial stages of documentation development, you give an overview of your software system. Usually, this is a demonstration and a verbal explanation. Sometimes, you must give us one or two days of formal training.
- When we start to look at your software in detail, your team must answer questions. Every few days, we will send you (or one of your team) a document with approximately five to fifteen questions. You give this document to your team, who give answers. Then you return the document to TechScribe. Refer to 'How to answer our questions'.
- Sometimes, your team must resolve conflicts. Different people sometimes give conflicting answers to questions. Sometimes, one person gives conflicting answers. That is why most of our questioning is done in a structured manner. An audit trail exists, and we can come back to your team and identify conflicts. This makes sure that the documentation is accurate, and shows the 'reality' that you want to give to your customers.
- Sometimes, when discussing concepts, the easiest way for us to understand is to speak with you. We then capture our understanding in a document, which we send to you, and which we ask you to verify.
How to answer our questions
During the documentation project, we will send you questions.
- Usually, we send questions in a Word document (questionsn.doc, where n is a digit). Change the file name to answersn.doc or to questionsn-response.doc.
- Send all answers at one time. Put the answers in the document, or refer to external documents. If the answers are all in one location, we can easily find the answers.
- If we ask a question that you cannot answer immediately, do not guess an answer. Write 'will be supplied later'.
- Respond with statements, unless a question is not clear to you. If you suggest something, make clear that it is not a request.
- Sometimes, more than one person gives answers. Sometimes, different people give different answers. We cannot know what your 'reality' is. Sometimes, part of our job is to help you to achieve an agreement, but we do not want to know about internal arguments. If an agreement is not possible, make an executive decision.
RSS feed