Documentation and user training
What is delivered with the software so people can use it and run it: documentation types, the four genres (tutorial, how-to guide, reference, explanation), release notes and training plan.
- 23 cards
- 3 topics
- Free
The outline, topic by topic
Each topic is weighted the way the exam weighs it.
- Concepts
- Questions
- Sort and link
A few cards from the deck
User documentation: what is it?
Show the answer
The documents meant for those who use the software to do their work, written in the words of their trade.
It explains what to do, not how it works inside: a user does not need to know the architecture.
Who is the operations documentation for?
- Those who run the software in production
- End users who enter the data
- Developers who add features
- Customers who decide on the purchase
Show the answer
Those who run the software in production
It describes start-up, backup, monitoring and recovery. Developers read the technical documentation, users the user documentation.
In the Diátaxis framework, the four genres of documentation are the … (learn by doing), the … (reach a goal), the … (look up facts) and the … (understand why).
Show the answer
In the Diátaxis framework, the four genres of documentation are the tutorial (learn by doing), the how-to guide (reach a goal), the reference (look up facts) and the explanation (understand why).
Mixing them on one page serves the reader poorly: a learner doesn't need a list of options, a looker-up doesn't need a story.
Technical documentation: what is it?
Show the answer
Documents meant for developers: architecture, design, interfaces, choices and rules for changing the code.
It conditions maintainability: without it, every newcomer must rediscover the choices by reading all the code.
Which of these training objectives is properly phrased?
- By the end of the session, the learner knows the invoicing module
- By the end of the session, the learner enters and sends an invoice unaided
- By the end of the session, the learner has seen the whole demo
- By the end of the session, the learner understands why invoicing matters
Show the answer
By the end of the session, the learner enters and sends an invoice unaided
An objective describes what the learner will be able to do, in an observable way, so it can be assessed. "Knowing" and "understanding" cannot be observed, and having seen a demo describes an activity, not something learned.