The PowerPoint slides for this week's lecture are here.
Software description and process, goals, market…
What constraints are you working under?
House styles, cost, manpower, skills, equipment, time…
Where are you going to obtain your information?
A named contact in software engineering team? Design documentation? Commented code? Non-functioning prototype? Alpha-version?
How can you contact the design team? What if they don’t reply? Who can wield a big stick for you? Can you let them know of your concerns and the interactions between software and documentation? Is there a feedback loop? What happens if you find flaws in the software or the interface design?
Who will check your work for technical accuracy?
Who will edit and proofread? Do they know what’s expected of them and when? Who will sign off your work as acceptable?
What can people do with the software? Does it replace or update existing packages? Is it like anything else? Which O/S does it run under?
Who are the users you are writing for?
User classes? Features of each class of user? Context of user classes?
What will each class of user be doing with the software?
Tasks of each user class. Do some overlap? Are some quite distinct?
Deliverables
Product profile
User profile, ideally as personas: these are some example personas from the Fabula case study.
On this basis -
what documents, paper and on-line, do you need to produce?
| what individual documents might you need to think about developing? (use decision matrix to decide) | reference manuals, user guide, tutorial, quick reference sheet, poster, keyboard overlay, on-line help, on-line tutorial, video, illustrated mouse mat, etc |
| good for obtaining management (or group) authorisation for the suite of documentation you’re planning | try to let the software developers know what you’re planning - it will help them appreciate your requests for information, etc |
| necessary for effective planning of process | will you have time and funding for the documents you would like to produce? Does your team have the skills to produce an animated tutorial? Will some documents need translation? What can safely be produced first, before the software is fixed? |
Deliverable
Library specification
Write a detailed description
of your intentions for each individual document or information object:
Deliverables
Document specifications
Prototype pages
Make a plan covering:
| how the document set will be developed | who will write what? which authoring system? who produces the proofs? will graphics be in-house? can you obtain screen-dumps at the right time? will you re-use existing styles and sections? |
| how the documents will be produced | commercial printers? is photocopy good enough? |
| if and how they’ll be updated | inserts, new versions on CD-ROM, registration in documentation? |
| costs | for development, production, translation, illustration. copyright, equipment … |
| schedules | milestones and deliverables, penalties… |
Deliverables
Final Documentation Plan
Schedule
Cost estimate
Now you have a plan, you can begin to draft some text… Click to go to More Steps