Closed9

Technical Writing: How to Write Software Documentation

Technical 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

https://www.udemy.com/course/start-your-career-as-user-assistance-developer/learn/lecture/23266724#announcements

1-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分

  1. Start with the 1st screen
  2. Describe pages and their intended use
  3. Describe what the customers see onthe screen
  4. 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分

  1. Identify the tasks that the customer needs to perform.
  2. Sequence them in a logical order.
  3. Add supporting concepts and information that the customer needs to know
  4. 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分

https://support.apple.com/ja-jp/guide/iphone/iph7a2a9399b/ios

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

https://qiita.com/e99h2121/items/12d6e1687c68a018b141

1-17. Technical Writer in the Software Development Team 2分

  1. Customer actually paying for
  2. Designs the UI
  3. Developer

Collects and organizes the requirements

1-18. The Technical Writing Process 4分

  1. Research and collect information
  2. Begin writing all down dump information
  3. Begin to structure and organize the information draft
  4. Present to stakeholders and collect feedback
  5. reflect the feedback in the documentation prepare final delivery
  6. Publish
  7. 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分

https://github.com/JordanStanchev/Getting-Started-as-User-Assistance-Developer/wiki/Jordan-Stanchev---Instructor's-Example
  1. Create a new repository on GitHub.
  2. Create a new page in your GitHub Wiki.
  3. Create a page (topic) title and subtitle (H1 and H2)
  4. Create a table
  5. Create images
  6. Create links
  7. Create a TOC (table of content) on a large wiki page

https://github.com/e99h2121/Getting-Started-as-User-Assistance-Developer/wiki

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-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

3-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

https://www.ox.ac.uk/sites/files/oxford/media_wysiwyg/University of Oxford Style Guide.pdf

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分

https://github.com/JordanStanchev/Getting-Started-as-User-Assistance-Developer
price of the coffee and sandwitch by using calclator

4-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.

https://ja.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

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

https://jpdocu.teachable.com/

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分

https://github.com/JordanStanchev/Getting-Started-as-User-Assistance-Developer/wiki/Students-List

4-71. Demo: How to Create and Use the Topic Types in the Wiki Page 10分

4-72. Wiki Markup - Instructor's Sample Code

https://github.com/JordanStanchev/Getting-Started-as-User-Assistance-Developer/wiki/Jordan-Stanchev---Instructor's-Example

"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

https://www.oasis-open.org/

6-90. The DITA Specification 2分

https://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/introduction/about-the-dita-specification-base.html

6-91. Overview of the Specification 7分

http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html

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.

http://docs.oasis-open.org/dita/v1.2/os/spec/common/task2.html#task2

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/

https://www.oxygenxml.com/xml_author/download_oxygenxml_author.html

JPDocu1x

6-99. End-to-end Demo 31分

https://www.antenna.co.jp/dita/dita-intro.html

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.

https://jpdocu.teachable.com/blog/91350/purchase-bus-ticket

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

  1. Prepare the money before you get on the bus.
  2. Get in the bus from the front door.
  3. Ask the driver for a ticket, by saying: “Bilet, molia!”.
  4. Give the money to the driver.
  5. Wait for the driver to give you the ticket.
  6. 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/

https://www.canva.com/ja_jp/presentations/templates/

8-119. What is Information Architecture? 2分

Art and Science of organizind and labeling websites, onine communicatinos.

https://www.amazon.co.jp/情報アーキテクチャ-第4版-―見つけやすく理解しやすい情報設計-Louis-Rosenfeld/dp/4873117720/

8-120. Who is an Information Architect and What Does an IA Do? 4分

https://www.lego.com/ja-jp/categories/vehicles/building-instructions

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

このスクラップは2ヶ月前にクローズされました
作成者以外のコメントは許可されていません