Technical Writing: How to Write Software Documentation
YAMADA NobukoTechnical Writing: How to Write Software Documentation
先生: https://www.udemy.com/user/jordanstanchev/
コース: https://www.udemy.com/course/start-your-career-as-user-assistance-developer/
コースとは関係ない先生のスライド: https://github.com/JordanStanchev/Getting-Started-as-User-Assistance-Developer
1. Getting started with Technical Writing
1-1. What will you learn in this section? 7分
actual basic
actually really stands for
various type of technical writing.
- functional
- task oriented
deliverables or anything
this help programming but no programming knowledge is needed.
Jordan stangy
work for a software company junior software developer
technical communications how my story started and I had to develop
actually different types
1-2. What is Technical Writing? 4分
Professional information communicator?
Facilitator better understande how to use particular software.
creation of information
how to present information
graphic info-graphic visual also how to create a special type of videos
how to use piece of product
1-3. Who is Doing Technical Writing? 6分
principles of technical writers
happening under different title of job titles
content management system
writing aspect of work instructional vides
move forwared to the publishing
user assistants aim to do is help your users
inforation architecture help our customers
1-4. What is the Result from Technical Writing? 2分
Particular goral
User guides the manual
QuickStart easily get started to the product
properly correctly use the software
instructional video that you are having
1-5. The Job of the Technical Writer 4分
not just the writing
planning
preparing
creating
structruing, organizing
clasifying
delivering and
maintaining
different set of requirement.
1-6. Types of Documentation 1分
Common types of documentation
easy to say blank page syndrome we don't know what we write
task oriented
1-7. Functional Documentation 3分
What customer see.
This button is doing this or something like that.
physical product
1-8. Functional Documentation - Example 2分
examples
SAP Cloud Platform Launchpad
What is Launchpad?
例: https://help.sap.com/viewer/8c8e1958338140699bd4811b37b82ece/Cloud/en-US/5a293715014342ffacaa4726f0fb7196.html
screenshot, diagram
entry point
simple as the start
see exactly the screen
1-9. Functional Documentation in Software Documentation 8分
examples IKEA
YAMADA Nobuko1-9. Functional Documentation in Software Documentation 8分
examples IKEA
physical oriented
software product
functional documentation should not spent time
not a practical type
because the goal is simple and easy to use
"new name button" the instruction tell nothing
well written documentation
it is like "comment" in source code
UX is so important ease of use the software is the exactly what we should do.
1-10. Strategy for Writing Functional Documentation 4分
- Start with the 1st screen
- Describe pages and their intended use
- Describe what the customers see onthe screen
- Organize the content in the order it appears on the user interface (UI)
1-11. Task-Oriented Documentation 4分
task oriented is different
not just getting started
Advanced usage of product
task-oriented is achieving results
why did the customer purchase
completely different type of software
acheve the goral
by default task oriented should be considered
1-12. Strategy for Writing Task-Oriented Documentation 11分
- 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.
Logical order
create account
setup account is no need
1-13. Task-Oriented Documentation Example 6分
the more shimple is your product the less documentation you provide
prerequisits are clear
Oprional
1-14. What is Software Documentation? 2分
"Great tool I know what will happen when I click here"
"Oops, what do I do now?"
1-15. Technical Writers in the Software Development World 3分
For the customers:
Helping users to effectively set up and use software
Assisting the users in solving a problem by themselves
Makin customers happy when using the software
For the software development team:
saving time and energy of th development team
1-16. Technical Writing Deliverables for Software 2分
user guide
API doc
helpful instruction , screen
instructional video or image, voice instruction
Metadata provided to a machine for search
YAMADA Nobuko1-17. Technical Writer in the Software Development Team 2分
- Customer actually paying for
- Designs the UI
- Developer
Collects and organizes the requirements
1-18. The Technical Writing Process 4分
- Research and collect information
- Begin writing all down dump information
- Begin to structure and organize the information draft
- Present to stakeholders and collect feedback
- reflect the feedback in the documentation prepare final delivery
- Publish
- Collect customers feedback and maintain
1-19. Exercise 1分
calculator application
how it works
When start calculation.
- Press AC Button. It is Reset the calculation.
- Press any number of the calclator.
- Then press + when you add the number.
- Finally press equal (=). Then the answer will be shown.
1-20. The Ultimate Purpose of the Technical Writer 1分
Feel happy.
小テスト1: Test Your Knowledge: Documentation in the Software Development World
Is the technical writer involved in the development of the software functionality?
No.
Does the technical writer take care of designing the user interfaces?
No.
2-21. Writing Documentation Using GitHub Wiki 8分
- Create a new repository on GitHub.
- Create a new page in your GitHub Wiki.
- Create a page (topic) title and subtitle (H1 and H2)
- Create a table
- Create images
- Create links
- Create a TOC (table of content) on a large wiki page
2-22. Overview - Sample Setup in GitHub 3分
2-23. What is GitHub? 1分
deliver high quality documentation.
originate the source at github is natual.
GitHub wiki is not enough. too many limitations.
2-24. Why Writing in GitHub? 5分
like a source code
basic standard use of GitHub
2-25. Documentation in GitHub 2分
2-26. Markup Language in Wiki Pages 1分
straightforward to use.
Markdown is standard one.
2-27. Instructor Examples in GitHub 8分
Wiki page
permission
switch to preview
2-28. Exercises Summary - What We Shall Perform in This Section 2分
exercise
account on GitHub
2-29. Set up Account in GitHub and Create a New Wiki Page 13分
2-30. How to Create a Table in GitHub Wiki Using Markdown 5分
2-31. How to Create an Image in GitHub Wiki using Markdown 7分
2-32. How to Create a Link to a Mail Address in GitHub Wiki Using Markdown 3分
2-33. How to Create a Table of Content (TOC) in GitHub Wiki Using Markdown 2分
2-34. How to Include a YouTube Video Reference in GitHub Wiki
YAMADA Nobuko3-35. How to Use a Style Guide in Technical Writing 10分
Style Guide
or standards and guidelines for writing
the style you have to use is different
documentations to be adjusted to the context
friendly people oriented
business software
payroll for the employee
official style and language in context
branding guidelines
in front of eyes in customeres
address the user the image of the company
it is the face
3-36. What is Style Guide? 2分
What is a style guide? Why do you need to care about the writing style in technical writing?
Which are some common style guides you can re-use already for writing software documentation
What are some common style rules you must apply in your software documentation writing?
How far should you go applying the rules of style guide in your company.
3-37. Why do we Needs Standards for Writing? 5分
Branding reasons - match style of writing with the company brand
-
We want to bring content that looks and is perceived as consistent and clear from the users.
-
We need to define rules that allow us to bring clear information to the target users
-
Can raise the quality and satisfaction of the product.
3-38. Sample Style Guides 1分
3-39. 3 Sample Style Guides 13分
Define the guidelines for writing
- Headings THIS IS A HEADING
- Paragraphs With an empty paragraph between them
- Sections are allowed. Sentence style, bold, no full stop at the end
- Bulleted lists:
- Para 1
- Para 2
- Numbered lists:
1.
2.
3.
University of oxford style guide
Abbreviations, contractions and acronyms
Capitalisation
Structure, Minimalism, Precision, Simplicity, Usability
Structure well.
- Headings
- Paragraphs
- Sections
- Tables
- Bulleted lists
- Numbered lists
Positive
ok: To receive the notification, enter your code
ng: Do not enter your name
Consistency
3-40. Who Else Needs Rules for Writing? 3分
Who needs:
- User assistance developer (technical communicator or technical writer)
- Content editor
- Translator
- Software architect
- Product owner
- Software developer
- Usability exparts(UX)
3-41. Results from Using a Style Guide 2分
Well organized content
Simplicity
Conciseness
Preciseness
3-42. Structure in Writing 7分
Good organization/structure
- Structure your content logically. Pay attation to how you will organize
- Headings
- Paragraphs
- Sections
- Tables
- Bulleted lists
- Numbered lists
3-43. Conciseness 2分
Avoid redundancies
Link to information instead of copying text
Use visual aids (diagrams, schemes, screenshots, etc)
3-44. Simplicity 2分
Use simple language and grammar
Use short sentences
Use positive formulations.
Do not use llong series of nouns that modify one another or a long series of propositional phreases. Insted, split them up into smaller manageable parts.
Use American English.
3-45. Precision 6分
Write true information:
Use correct and consistent terminology.
Use correct navigation paths.
Use correct product or component names.
Cost money.
Double-check.
3-46. Verb Choice: Can or May? 1分
Good: Change Save Delete Import Create...
Bad: Maintain
Can or May?
Can = possible for the user or the system.
May or might = possible state or outcome.
3-47. Verb Choice: Must/Must not/Should/Shouldn't/May 1分
MUST = an absolute requirement
MUST NOT = "shall not" - absolute prohibition
SHOULD = "recommend" there may exist valid reasons
SHOULD NOT = "not recommend"
MAY = "optional" you can choose.
3-48. Active Voice and Present Tense 1分
Use active voise
If appropriate for text type and context, address the user directly with "you"
Define clearly who does what(the user, the application, the system admin)
3-49. Terminology 1分
Disucuss terminology together with developers with POs. UI designers.
Use correct and consistent terms.
Be careful inventing your own terms or jargon
Do not use the same word to mean different things : umbrella terms
3-50. Consider in Addition 1分
Contractions( don't can't
Humor avoid
Gender do not assume the gender of your users; use him or her
Jargon words or idioms
3-51. Use Tools! 3分
Use a spell-checker!
Search for existing terms/expressions on the web
3-52. UI Messages and Text on Screen 1分
UI Messages and Text on Screen
"Catastrophic failure"
3-53. Exercise 1分
price of the coffee and sandwitch by using calclator
YAMADA Nobuko4-54. Structured Writing 2分
How to write a doc in structured writing
particular examples
particular templates
4-55. Why Do We Need Structure in Writing? 1分
4-56. Organizing Large Amounts of Content 1分
4-57. Consistency in User Experience 1分
Organizing large amounts of content
multiple functionalities
Structures consistent
holistic experience
4-58. Intuitive and Obvious User Experience 1分
Obvious experience
4-59. Ensuring Completeness of the Documentation 1分
Ensuring the completeness of documentation
Easier to spot a gap
4-60. Targeting Content to Various Audiences 2分
something monolithic
would not want to read the rule
4-61. Coordinating Documentation Projects 2分
coordinating writing projects among a group of writers
write documentation together
specific struecure will work
4-62. Increase Understandability of the Documentation 2分
consistent logical
much faster
particular problem
4-63. Structured Writing: Definition 1分
Form of technical writign that uses and creates structured documents.
Rebert E. Horn
information block
4-64. Common Information Types 1分
concept
procedure
process
principle
fact
structure
classification
4-65. DITA XML - a Standard for Structured Writing 5分
Darwin Information Typing Architecture(DITA) XML topic types:
Information type: Description
Concept: Conceptiual information answering "What is this"
Task: Provide instructional information answering "How to do this"
Reference: additional information, such as a table with reference values, or additional informaiton.
4-66. How to Structure in an Unstructured Writing Environment? 1分
How to structure Unstructured writing:
Define and use topic templates to represent the structure of the information you have to provide
4-67. Structured Writing in Microsoft Word Environment 9分
4-68. Details of the Topic Types in the MS Word Template 10分
unstable when we write large document.
nightmare tables
Software Documentation templates
Overview
Instructions
Templates
4-69. Structured Writing in GitHub Wiki 4分
Structured Writing in GitHub Wiki
Can be amulated using titles.
Can be done using multiple pages or a single wiki page with TOC.
several small different pages share.
4-70. Details of the Topic Types in the GitHub Wiki Template 5分
4-71. Demo: How to Create and Use the Topic Types in the Wiki Page 10分
4-72. Wiki Markup - Instructor's Sample Code
"Caluculator" is application name?
10 roles of the documentation
## Concept
### Summary
### Detailed Overview
### Excercise
5-73. Principles of Technical Writing 12分
all about customers
not about writing
skill: hard skills and soft skills
actuall writing easy to be understood.
terminology. through documentation.
Wiki pages GitHub Wiki.
Oxigen DITA
by heart.
very oftene people job.
focus on your work.
Soft skills: better and excel the career.
excel at communications.
skills of communiations.
find your ways close to them.
related to the content
Speaking.
talk to the customers.
What is the environment in which ways.
not single conversations.
key stakeholders.
embrace
5-74. Principle #1: Decide Who are You Writing For 4分
Describing the user interfaces.
Defferent information needes
figure out who the customers.
Aiming for
militally, not allowed to connect to the internet.
how many screen they use.
ages of their age.
5-75. Principle #2: Identify the Information Needs 2分
Searching for:
What format they use.
5-76. Principle #3: Decide on the Style 5分
ORDER
CHAOS
formal or Dry
spectrum
aligned of the company.
5-77. Principle #4: Decide Which Deliverables to Create 7分
deliverables to create
one PDF
indentified target groups
functional documentation.
agile mode
lengthy deadline
use JIRA
5-78. Principle #5: Decide Which Tools to Use 7分
Microsoft Word is good tool but nightmare.
DITA XML format.
5-79. Principle #6: Define the Content Structure 7分
precice information.
lose customer.
integrated with software.
5-80. Principle #7: Decide Which Information Channels to Use 5分
tend to read less and less
nobody enjoy reading documentation
infographic right balance
5-81. Principle #8: Write the Documentation 1分
5-82. Principle #9: Use Images and Video When Appropriate 5分
information visual mannar
demonstration. graphic or a video.
5-83. Principle #10: Publish the First Version 2分
relevant necessary information
5-84. Principle #11: Collect Feedback and Improve 2分
5-85. Principle #12: Repeat! 2分
inprove.
5-86. Exercise on Applying the Principles in Documentation 1分
5-87. Instructor's Example on Applying the Principles in Documentation 4分
1. Who are you writing for My target user is:
2. What information does my user need?
3. I am going to use ... style.
4. I am going to develop a ... deliverable.
5. I shall create my instructions using...
6. I shall structure my content in the following way:
a. Features overview
b. Tasks with ...
c.
d.
6-88. What is DITA? 1分
XML data model for authoring and publishing purposes.
6-89. Who Defines DITA? 1分
OASIS Darwin Information Typing Architecture.
OASIS OPEN
6-90. The DITA Specification 2分
6-91. Overview of the Specification 7分
6-92. Do You Need to Know the Specification by Heart? 1分
NO!
6-93. Basics of Structured Writing 21分
Introduction to DITA
a form of technical writing that uses and creates structured documents.
Identified over 200 common block types.
Assembled into information types using information maps.
7 common information types:
concept
procedure
process
principle
fact
structure
classification
XML format
XML stylesheet
Darvin information typing architecture
process and procedure
Why do we need structure in writing?
Organizing large amounts of material
Maintaining an orderly structure to provide a consistent experience to users
Providing users with a more intuitive and obvious experience
Ensuring the completeness of documentation
Targeting content to varying audiences
Coordinating writing projects among a group of writers
Organizing each chunk of content in an intuitive way
Organizing pages of content in a way that helps users understand its place in the whole body of knowledge
Maximizing a efficiency with which documentation cab be understood and used.
Information types in DITA
concept
task and
reference
DITA Concept topics answer "What is.." questions.
Use the concept topic.
Task:
"How do I?" questions, and ahve a well-defined.
Reference:
suitable for biblographies, catalogues, recipes...
6-94. Understanding DITA: Authoring Point of View 8分
Authoring in DITA
Based on information types.
Task, Concept, Reference
Deliverables structures is organized outside the topic.
Implies that the author shall follow strict rules for writing.
Modularized and reusable.
Context-free
6-95. Understanding DITA: Information Architect Point of View 7分
Different levels of content reuse - deliverable, map, topic, topic element.
Enables the development of linking strategy - accross deliverables, between maps, between topics;
automatically generated links or manually inserted links
Filtering and flagging of the final deliverable, based on profiling values (conditions)
6-96. How to Install the Software for This Section 1分
6-97. Oxygen XML Author 1分
Choose an editor of choice
6-98. Installing a Tool for Writing with DITA 4分
oxygen XML editor
oxygenxml.com/
JPDocu1x
6-99. End-to-end Demo 31分
6-100. Exercise 1: Write a Sample Instruction 1分
6-101. Instructor's Example: Writing DITA Documentation Using Oxygen Author Tool 6分
6-102. Exercise 2: Writing Documentation using Oxygen Author DITA CMS 1分
Question 1:
Which target audience you considered before starting to write? Did this influence the way you structured your documentation?
Answer: I have chosen to target the large audience of end-users of the calculator application. These can be any people that need to perform some simple calculations.
Question 2: Which concept you decided to document? Why?
Answer: In my sample, I did not provide conceptual information. I could have provided a basic explanation of what is the idea behind adding numbers. However, this is already covered by the school education that most people using a calculator should have, so I assume most users will already know this information.
Question 3: Which tasks you decided to document? Why?
Answer: I have covered 2 basic tasks: how to start the application and how to add numbers.
7-103. Introduction & Materials to Download for This Section 6分
GRAPHICS IN SOFTWARE DOCUMENTATION
7-104. Agenda 2分
What will you learn?
• Why do we need graphics? When to use a graphic?
• Types of graphics in technical writing
• Using tools to easily create graphics
7-105. Why Graphics are Important? 4分
Why?
Castelhano and Henderson’s Perception of
Scene Gist
“As humans, we have the ability to gather
context based on what we see. When we fix our
eyes on something, we have the ability to form
an understanding of the environment and
recognize the meaning of a scene.”
7-106. When to Use Graphics in Software Documentation? 5分
When?
When it is
possible to
provide the
information in a
visual way;
When you
need to explain
complex set of
steps or
architecture.
7-107. Types of Graphics in Software Documentation 1分
TYPES OF
GRAPHICS IN
SOFTWARE
DOCUMENTATION
7-108. Process Graphics 3分
TYPES OF
GRAPHICS:
PROCESS
7-109. Architecture Graphics 3分
GitHub
Starting place where your project begin.
7-110. Infographics 5分
Entire infographics
7-111. Rules for Graphics in Technical Writing 10分
Consistent
Rules for Graphics in
Technical Writing
• Always explain what’s in the graphic using text.
• Adhere to rules for accessibility:
– image ALT text;
– colors that does not confuse or affect people with color
blindness, for example;
• Use consistent colors and styles across the documentation, as per
your company style guide
• Consider translatability options for your images (is it possible to have
the text in your graphic translated?).
7-112. Tools for Creating Graphics 1分
Tools for
Creating
Graphics
• MS Power Point
• Google Slides
• https://app.diagrams.net/
• https://www.easel.ly
7-113. Tools for Creating Graphics Used in This Section 2分
To pay for a bus ticket in Sofia, you have several options:
• Purchase the ticket beforehand from the kiosk for bus tickets.
• (Recommended) Purchase the ticket from the bus driver
• Purchase the ticket from a ticket machine in the bus.
7-114. Exercise Procedure 2分
canva.com/
How to purchase the ticket from the bus driver in Sofia, Bulgaria?
Overview
To use the public transportation in Sofia, Bulgaria, you need to purchase
a single-person ticket. This ticket costs 1.60 BGN. You buy it from the
driver.
If you carry a larger bag or you have a dog or a bike with you, in addition
you must purchase additional ticket (again 1.60 BGN) for it too.
If you have with you children younger than 6 years - they travel free of
charge – no need to purchase a ticket for them.
Steps
- Prepare the money before you get on the bus.
- Get in the bus from the front door.
- Ask the driver for a ticket, by saying: “Bilet, molia!”.
- Give the money to the driver.
- Wait for the driver to give you the ticket.
- Find the special punching device and use it punch the ticket.
Note: If you do not do that, you may pay a significant fine, in case
you are being checked by the authorities! It is not enough if you
only purchase the ticket
7-115. Exercise Goals 1分
7-116. Exercise Sample Procedure 2分
7-117. Using Microsoft PowerPoint 2分
7-118. Demo: Using Microsoft PowerPoint 17分
7-119. Exercise - Step 3 - Demo of Tool 24分
canva.com/
YAMADA Nobuko8-119. What is Information Architecture? 2分
Art and Science of organizind and labeling websites, onine communicatinos.
8-120. Who is an Information Architect and What Does an IA Do? 4分
8-121. Why Should I Care About Information Architecture? 3分
Ask yourself:
- Do you want your documentation to be found in the internet?
- Do you want to be able to reuse documents in different deliverables?
- Do you want to allow authors to work an different projects?
- Do you want to reduce learning curve for entering a new project?
8-122. Information Architecture in Technical Writing 3分
- Providing a consistent warkign environmen
- Enabling and fastening reuse
- Consulting authors and helping them solve problems related to organization and docu delivery.
8-123. How to Apply Information Architecture Principles for the Content? 12分
- Target users
- Consumution patterns
- Product standard(s)
- Update cycles
Deliverables
Recipe
Customer's first
Standards
Deliveries
Delivery channels
Organize it logically
Reuse the content
Identify the organizational patterns
8-124. Structuring Data. Metadata and Taxonomies. 1分
Taxonomy and Classification
they come from biology