What is technical writing?
It is a special type of writing used when you need to explain to another person:
- what are the products or services you provide
- what are the features of this product or service
How to: install, set up and configure, use, maintain, dispose of
Technical writer/communicator
research and create information through a variety of delivery media (electronic, printed, audio-visual, and even touch).
Common Documentation Deliverables
User guide (a manual)
Quick start guide
Checklist
Instructional Video, etc.
Functional Documentation
Suitable for just getting started with a new product in the software world
Explains what you see in front of you
Helps find your way through the product
Often used for physical products (think ikea instructions for furniture)
Strategy for writing functional documentation
- Start with the first screen
- Describe pages and their intended use
- Describe what the customers see on the screen
- Organize the content in the order it appears on the UI
Task-oriented Documentation
Suitable fir advanced usage of a product
Barely explains what you see in front of you, instead focuses on how to achieve a certain result
Helps you find your way through the product or across multiple related products
Often used for software products
Guides you through the steps of a process
Strategy for Writing Task-Oriented Documentation
- Identify the tasks that the customer needs to perform.
- Sequence them in a logical order.
- Add supporting concepts and information that the customer needs to know
- Add supporting reference information that helps them later on, once they know the products better.
What is software documentation?
Written text that accompanies computer software
Technical Writing Process
- Research and collect information
- Begin writing all down (info dump)
- Begin to structure and organize the info (draft)
- Present to stakeholders and collect feedback
- Reflect the feedback in the documentation
- Prepare final delivery
- Publish
- Collect customers feedback and maintain documentation
What is GitHub?
web-based Git version control repository hosting service.
General principles for style of writing
- Structure well (organize in logical chunks using tables, headings, sections, lists, etc)
- Add visuals (graphics, diagrams, screenshots, etc)
- Write concisely
- Short and simple sentences
- Positive formulations (focus on telling someone what to do instead of what not to do)
- Active voice (make is clear who does what)
- “What” before “how” - explain what the action will do before instructing them on an action to take
- Describe actions in a chronological sequence
- In conditional sentences, place the condition before the statement (e.g. If you want to proceed, choose Next)
- In general, use the present simple tense
- Do not use jargon, slang, or colloquialisms
- Avoid using abbreviations
- No redundancies - check the text for repetition at different levels
- Cross-refer to information instead of copying text
- Formulate in a way that is free of stereotypes relating to gender, race, age, culture, ability, etc
Keep things simple
Don’t use long series of nouns or a long series of prepositional phrases
Verb Choice
- Use precise verbs
Can or May? - Can = possible for the user or the system
- May or might = possible state or outcome
Other verbs to consider
Must = requirement
Must not = absolute prohibition
May = options
Should = recommended
Shout not = not recommended
Why do we need Structured Writing?
- Organize large amounts of content
- Consistency in user experience
- Intuitive and obvious user experience
- Ensure the completeness of documentation
- Target content to varying audiences
- Coordinating documentation projects
- Increase ability to understand docs
Structured Writing
Definition = structured writing is a form of technical writing that uses and creates structured documents
Common information types
concept
procedure
process
principle
fact
structure
classification
DITA XML
Darwin Information Typing Architecture (DITA) XML topic types:
- concept
- task
- reference
DITA topics are assembled into documents using DITA maps
Structure of a concept
Summary
Detailed Overview
Example
Task
Structure of a task
Summary
Prerequisites
Steps
Result
Structure of Reference
Most freely designed sections
Typically begin with “summary” and then whatever else is needed
Principles of Technical Writing
- Decide who you are writing for
- Identify the Information Needs
- Decide on style
- Decide which deliverables to create
- Decide which tools to use
- Define the content structure
- Decide which information channels to use
- Write the documentation
- Use images and video when appropriate
- Publish the first version
- Collect feedback and improve
- Repeat
What is DITA?
OASIS Darwin Information Typing Architecture
defines a set of document types for authoring and organizing topic-oriented information, as well as a set of mechanisms for combining, extending, and constraining document types.
