Technical Writing: How To Write Software Documentation

Learn a proven strategy for writing software docu in GitHub wiki based on the 12 main principles of technical writing!

What you'll learn
Learn what is required to start working on the software documentation for an app
Learn how to write documentation in GitHub Wiki using Markdown
Try out tools and infrastructure that helps you immediately get started writing your help content
Learn how to prepare, structure and develop information that help users use your software
Learn the basics of structured writing
Understand the importance of metadata and taxonomies to improve for your user assistance assets findability
Use Oxygen Author tool to write sample documentation using DITA maps and DITA topics
Learn how to make graphics for your software documentation using SmartArt in MS Power Point and Google Slides
Requirements
You will need a PC or a laptop where you can develop content assignments or install particular software we will be using on trial basis in the course of the training
Description
Is the ability to provide relevant information about using your software essential for your customers? Do you find yourself spending hours and hours trying to explain how to use the software? Or are you getting feedback from your clients that your documentation is hard to be followed, inconsistent or maybe even…. confusing? If you answered with "Yes!" to any of these questions and are willing to invest the time and energy needed to go through this practical course, then this course is for you! CNBC cited this course in the article "The 20 hottest job skills companies are looking for right now"By the end of this course:You will be able to describe the processes and principles for writing. You will be able to explain the process for preparing, organizing, and delivering software documentation for the users of software products.You will be able to create instructional images and graphics needed in your documentation. You learn and practice how to create software documentation in a GitHub wiki following the instructor's templates for writing.Also:You will find out also which are the core principles for writing software documentation that really helps.You will have the chance to try out GitHub wiki editor and Oxygen Author DITA XML tools for writing. You will learn about the importance of graphics and which tools you can use to create instructional graphics with ease.In the end, you will find out more about what metadata is and its importance in software documentation. Ultimately, you will have the chance to create your own documentation project and receive personalized feedback on your work from the trainer!In the course of the years, the core activities of technical writing professionals have constantly been evolving. We started as technical writers and focused solely on technical writing. We transformed into information developers that also consider the graphical aspects and design of the content.  Today, we need to bundle together writing skills, design and graphics, video creation, multimedia, metadata, and software development to meet the expectations of our users. All these assets put together can be described together as user assistance.For several years now, JPDocu School of Technical Writing has been designing and delivering training on user assistance for:technical writers (information developers)information architectssoftware developers The instructor, Jordan Stanchev, a User Assistance Development Architect has personally trained hundreds of people in the classroom, in online courses, in universities, and internally at a Fortune 100 company! Jordan says: "The goal for me has always been to deliver practical information, to make sure my trainees get ready for delivering real content right after the course is over. I am so proud of my students who come back to me and share how they have started their first job as a technical writer or how they have advanced in their careers using what they have learned in my courses!That's why I have started devoting my time to teaching technical writing skills, on top of my regular job as a User Assistance Development Architect."Unlike other courses out there,  this course is practically oriented. It will help you develop your portfolio and work samples you need to apply as a technical writer in a software development company. What will you learn?This course is designed for beginner technical writers, usually students in IT, and covers the following subjects:What is technical writing all about? What are the basics of technical writing? Which are the main principles that you should follow to construct and build your documentation?Which are the common terms you will hear and use in the IT technical writing world?How to write technical documentation using GitHub wiki? You will, later on, use this material for creating your portfolio that you will want to add to your CV when you apply for a technical writer job or promotion to a senior developer. What is information architecture from a technical writing point of view?By the end of this course, you will know how to get started writing your user guides, which best practices and rules to consider, and which tools to use for writing.Besides:You will also find recorded webinars to give you the feeling you are in the university classroom together with other students doing the actual exercises of the course. You will have access to a closed community group, where you can learn together with other students in technical writing.You will have the chance to participate in live webinars with the instructor, to get guidance and answers to questions you may have.Downloadable workbooks in the sections to help you as you go through the content and practice what you have learned.What is NOT COVERED in this course?Learning technical writing as a beginner technical writer will take at least 2 semesters at the university and lots of writing practice. It is impossible to provide deep-dive information on all possible technical writing subjects in a 4-6 hours course. You will know the basics, though!This is not a course on writing using MS Word! We are not going to write books! We are not going to write unstructured documentation!Unlike what other courses on technical writing will tell you MS Word is the worst choice for writing technical documentation!  It cannot scale, and it is not flexible enough for software documentation! If you believe that technical writing is about writing books, please choose another course! This course is for people who want to work in the software industry, where writing a book and calling it "software documentation" is not perceived well!Technical writing is a skill and discipline that requires writing. Do not expect to become a technical writer by listening to a few lectures. You will have to write and communicate in this course. This is not a course for listening, but a listen and do it! type of course.This is not an English language course. I will not provide you with details on how to write in English. There are so many tools you can use for writing. In this course, I do not go into details on tools you can use for writing but directly suggest using only 1-2 of them to get you started. We do not cover API documentation in this course. API documentation is a type of software documentation that you still have to deliver, but at present, this course does not talk about that. Look at our dedicated API course on this subject.How much time will it take for you to go through this course?Short answer:Section 1: Getting Started with Technical Writing - 70  minSection 2: Documentation in the Software Development World - 10 min Section 3: Writing Software Documentation in GitHub using Markdown - 1 hourSection 4: Style Guide in Technical Writing (or Standards and Guidelines for Writing Docu) - 1 hourSection 5: Introduction to Structured Writing - 1 hourSection 6: The 12 Principles of Technical Writing - 1 hour Section 7: Software Documentation Development using DITA XML in Oxygen Author - 1 hour 30 minSection 8: Using Graphics and Images in Software Documentation - 1 hourSection 9: Strategies and Information Architecture - 40 minBonus Section 1: Webinars - 60 to 90 min per webinar in this sectionBonus Section 2: Quality in Documentation - a Quality Framework Research and Practical Applications - 45 minDetailed answer with explanation:Section 1: Getting Started with Technical Writing (as a compliment to you, because you got to this part of our detailed course summary, this over 1-hour long section comes for free - it's a mini-course by itself! Even if you decide not to purchase the entire course - you should definitely check it out.)  We start with a quick and direct overview of the end-to-end documentation creation processes.Basically, when you go through the introduction section, you should get a basic understanding of what technical writing in software documentation is all about, as well as the main assets (deliverables for your customers) that you create using technical writing skills and techniques. This is the software documentation, images as well as instructional videos, and multimedia.It could take approximately half an hour to go through the material and do the exercise in the section.Section 2: Documentation in the Software Development World - 10 min What is the place of the technical writer in the software development team? Which are the steps of the technical writing process to follow?Section 3:  Writing Software Documentation in GitHub using Markdown - 1 hourHow to get started writing in a Wiki on GitHub? This section explains the setup steps, and the markup language used in the wiki and gives you hints on Markdown language usage (that is not well-known or documented in the wiki!), such as:- how to create a table- how to create images on Wiki- how to create a Table of Content (TOC) for your longer pages- how to link a YouTube video with easeThis section touches upon a very important subject - how to provide documentation for a GitHub project. I talk about one of the possible options, and I would dare to say the most simple one, to provide documentation in GitHub.Section 4: Style Guide in Technical Writing (or Standards and Guidelines for Writing Docu) - 1 hourHave you ever wondered how successful software development companies bring a holistic user experience with their products? After all, companies like Apple, SAP, Oracle, and VMWare - have hundreds, even thousands of products. At the same time, it feels like their documentation was written by a single person!The user experience with the software is similar across the various products. The content is organized also using similar patterns… How did they achieve that? Maybe they employ a single super-technical writer who just works day and night? Or they were born thinking in one and the same way… no matter in which team they work in the company. Come on, there must be some secret here! What’s their secret?In this section, you will learn:- 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 reuse 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 a style guide in your company?Section 5: Introduction to Structured Writing - 1 hourHow to write in an unstructured environment? Why structure is so important for a technical writer? Which templates to use and follow when writing in DITA XML, Markdown in Github, or when writing using Microsoft Word documents? The section demonstrates how you can build entire documentation projects that help them create a portfolio to demonstrate their writing experience. Even if they are not experienced authors and do not have a dedicated project to work on. You can do that too - you can write sample documentation following this course, which will help you get the job of a technical writer! You can work solo or in a team with your friends on such documentation projects. You can write pages and pages of docu and guides using this simple wiki-based writing approach. When you take a look at the Bonus Section of this course, you will already see direct links to some of the small but impressive documentation deliverables other students have already created by following this course and allowed me to share back with you.In terms of time you will need to spend here, yes, it would take you like an hour to go through this section, but it can take you like another hour to create and set up a GitHub project to find my samples in there, understand the templates I propose that you use while writing, and really doing the writing job.Section 6: The 12 Principles of Technical Writing The next section begins to build upon what you have learned so far. This lecture will put things in perspective. You may find it simple, but do not underestimate it - this will be your recipe for success as a technical communicator and a technical writer going forward.Going through the section and briefly touching upon the main principles of technical writing, the tools, and the time you need to spend performing the exercises all together can take around 1 hour of your time.Section 7: Software Documentation Development using DITA XML in Oxygen Author - 1 hour 30 minTry out one of the most popular tools for writing DITA and in general XML-based software documentation.In this section, you will try out Oxygen and create documentation using it.Section 8: Using Graphics and Images in Software Documentation - 1 hourHow important is the graphics creation skill for technical writers? I would say, A LOT! This section talks about the rules for creating graphics in software documentation. Also, I touch upon tools that make it easy to create graphics without having to become a graphic designer.It will take approximately 1-2 hours to go through this content and perform the exercises. Section 9: Strategies and Information ArchitectureThen comes the next section - on information architecture and metadata for technical writers. It opens the door for you to take a look at the basic knowledge that an information architect (think about it as a very experienced technical writer) needs to have to begin doing his or her job. This section is more like an overview of the metadata concepts and possible scenarios you can enable as a technical writer. No special exercises in this course, as this goes a bit far ahead of what a regular technical writer is supposed to do.In terms of time to spend, you will need like 30 min to go through it.Bonus Section 1: WebinarsHere the really fun part begins. You will find several recordings of live seminars I do with JPDocu School of Technical Writing students. You can listen to these recorded sessions and participate as if you are really in the classroom together with me and the rest of the class. I think this can be a very cool experience. On top of that, we deep dive into subjects that were only briefly touched upon in the previous sections.Each recorded session takes 60-90 minutes, including the work on the exercises in each session. As part of the course here, I invite my students to participate in such live webinars, which you can see in our closed Facebook group. Bonus Section 2: Quality in Documentation - a Quality Framework Research and Practical Applications - 45 minIn 2021 we initiated research to define the meeting of quality in the documentation. Many participants joined and shared their feedback. After analyzing and aggregating the results, the research results are ready to be shared with JPDocu School of Technical Writing students!The research recap is shared in this bonus section, giving you answers to:What is quality when we speak about documentation?What are the characteristics high-quality documentation has?What is the specific meaning of each of the quality aspects that you must strive to achieve in documentation?How to develop practical ways to measure quality in your documentation and compare it against other documentation deliverables?This will help you not only to create some documentation but instead, to build high-quality documentation that trills your customers!Here is what students say about this course:Karina Delcheva, Technical Writer"I find Jordan's course perfectly structured (as you would expect of a specialist in the field) in a way that helps you grasp the concept of technical writing. It helped me quickly develop practical skills through exercises with easy-to-follow instructions and examples. The Facebook page of this course provided me with a supportive community and additional webinars held by the lecturer, which is a great asset for acquiring more diverse skills needed by a technical writer. Now I feel prepared to apply for my first technical writing job."Grace Tan, Technical Writer"In my pursuit of moving to a technical communicator role, Jordan's beginner course Technical Writing: How to Write Software Documentation has put me in the right direction. The course is well-structured, and the instructor has shown expertise in this field. It is great to be in touch with the standard and best practices in technical writing as well as the common tools that are used nowadays. I also had fun working on hands-on activities and getting myself familiar with different tools."So, enroll now and see how easy and simple it is to deliver the ultimate help to your customers! P.S. This course has a 30-day full refund policy - no questions asked!

Overview

Section 1: Getting Started with Technical Writing

Lecture 1 What will you learn in this section?

Lecture 2 What is Technical Writing?

Lecture 3 Who is Doing Technical Writing?

Lecture 4 What is the Result from Technical Writing?

Lecture 5 The Job of the Technical Writer

Lecture 6 Types of Documentation

Lecture 7 Functional Documentation

Lecture 8 Functional Documentation - Example

Lecture 9 Functional Documentation in Software Documentation

Lecture 10 Strategy for Writing Functional Documentation

Lecture 11 Task-Oriented Documentation

Lecture 12 Strategy for Writing Task-Oriented Documentation

Lecture 13 Task-Oriented Documentation Example

Lecture 14 What is Software Documentation?

Lecture 15 Technical Writers in the Software Development World

Lecture 16 Technical Writing Deliverables for Software

Section 2: Documentation in the Software Development World

Lecture 17 Technical Writer in the Software Development Team

Lecture 18 The Technical Writing Process

Lecture 19 Exercise

Lecture 20 The Ultimate Purpose of the Technical Writer

Section 3: Writing Software Documentation in GitHub using Markdown

Lecture 21 Writing Documentation Using GitHub Wiki

Lecture 22 Overview - Sample Setup in GitHub

Lecture 23 What is GitHub?

Lecture 24 Why Writing in GitHub?

Lecture 25 Documentation in GitHub

Lecture 26 Markup Language in Wiki Pages

Lecture 27 Instructor Examples in GitHub

Lecture 28 Exercises Summary - What We Shall Perform in This Section

Lecture 29 Set up Account in GitHub and Create a New Wiki Page

Lecture 30 How to Create a Table in GitHub Wiki Using Markdown

Lecture 31 How to Create an Image in GitHub Wiki using Markdown

Lecture 32 How to Create a Link to a Mail Address in GitHub Wiki Using Markdown

Lecture 33 How to Create a Table of Content (TOC) in GitHub Wiki Using Markdown

Lecture 34 How to Include a YouTube Video Reference in GitHub Wiki

Section 4: Style Guide in Technical Writing (or Standards and Guidelines for Writing Docu)

Lecture 35 How to Use a Style Guide in Technical Writing

Lecture 36 What is Style Guide?

Lecture 37 Why do we Needs Standards for Writing?

Lecture 38 Sample Style Guides

Lecture 39 3 Sample Style Guides

Lecture 40 Who Else Needs Rules for Writing?

Lecture 41 Results from Using a Style Guide

Lecture 42 Structure in Writing

Lecture 43 Conciseness

Lecture 44 Simplicity

Lecture 45 Precision

Lecture 46 Verb Choice: Can or May?

Lecture 47 Verb Choice: Must/Must not/Should/Shouldn't/May

Lecture 48 Active Voice and Present Tense

Lecture 49 Terminology

Lecture 50 Consider in Addition

Lecture 51 Use Tools!

Lecture 52 UI Messages and Text on Screen

Lecture 53 Exercise

Section 5: Introduction to Structured Writing

Lecture 54 Structured Writing

Lecture 55 Why Do We Need Structure in Writing?

Lecture 56 Organizing Large Amounts of Content

Lecture 57 Consistency in User Experience

Lecture 58 Intuitive and Obvious User Experience

Lecture 59 Ensuring Completeness of the Documentation

Lecture 60 Targeting Content to Various Audiences

Lecture 61 Coordinating Documentation Projects

Lecture 62 Increase Understandability of the Documentation

Lecture 63 Structured Writing: Definition

Lecture 64 Common Information Types

Lecture 65 DITA XML - a Standard for Structured Writing

Lecture 66 How to Structure in an Unstructured Writing Environment?

Lecture 67 Structured Writing in Microsoft Word Environment

Lecture 68 Details of the Topic Types in the MS Word Template

Lecture 69 Structured Writing in GitHub Wiki

Lecture 70 Details of the Topic Types in the GitHub Wiki Template

Lecture 71 Demo: How to Create and Use the Topic Types in the Wiki Page

Lecture 72 Wiki Markup - Instructor's Sample Code

Section 6: The 12 Principles of Technical Writing

Lecture 73 Principles of Technical Writing

Lecture 74 Principle #1: Decide Who are You Writing For

Lecture 75 Principle #2: Identify the Information Needs

Lecture 76 Principle #3: Decide on the Style

Lecture 77 Principle #4: Decide Which Deliverables to Create

Lecture 78 Principle #5: Decide Which Tools to Use

Lecture 79 Principle #6: Define the Content Structure

Lecture 80 Principle #7: Decide Which Information Channels to Use

Lecture 81 Principle #8: Write the Documentation

Lecture 82 Principle #9: Use Images and Video When Appropriate

Lecture 83 Principle #10: Publish the First Version

Lecture 84 Principle #11: Collect Feedback and Improve

Lecture 85 Principle #12: Repeat!

Lecture 86 Exercise on Applying the Principles in Documentation

Lecture 87 Instructor's Example on Applying the Principles in Documentation

Section 7: Software Documentation Development using DITA XML in Oxygen Author

Lecture 88 What is DITA?

Lecture 89 Who Defines DITA?

Lecture 90 The DITA Specification

Lecture 91 Overview of the Specification

Lecture 92 Do You Need to Know the Specification by Heart?

Lecture 93 Basics of Structured Writing

Lecture 94 Understanding DITA: Authoring Point of View

Lecture 95 Understanding DITA: Information Architect Point of View

Lecture 96 How to Install the Software for This Section

Lecture 97 Oxygen XML Author

Lecture 98 Installing a Tool for Writing with DITA

Lecture 99 End-to-end Demo

Lecture 100 Exercise 1: Write a Sample Instruction

Lecture 101 Instructor's Example: Writing DITA Documentation Using Oxygen Author Tool

Lecture 102 Exercise 2: Writing Documentation using Oxygen Author DITA CMS

Section 8: Using Graphics and Images in Software Documentation

Lecture 103 Introduction & Materials to Download for This Section

Lecture 104 Agenda

Lecture 105 Why Graphics are Important?

Lecture 106 When to Use Graphics in Software Documentation?

Lecture 107 Types of Graphics in Software Documentation

Lecture 108 Process Graphics

Lecture 109 Architecture Graphics

Lecture 110 Infographics

Lecture 111 Rules for Graphics in Technical Writing

Lecture 112 Tools for Creating Graphics

Lecture 113 Exercise Instructions

Lecture 114 Infographic Exercise - Expected Result

Lecture 115 Demo - Create Infographic Using Canva

Lecture 116 Creating Graphics Using Microsoft PowerPoint

Lecture 117 Demo: Using Microsoft PowerPoint

Lecture 118 Exercise - Creating Graphics Using Google Drive

Section 9: Strategies and Information Architecture

Lecture 119 What is Information Architecture?

Lecture 120 Who is an Information Architect and What Does an IA Do?

Lecture 121 Why Should I Care About Information Architecture?

Lecture 122 Information Architecture in Technical Writing

Lecture 123 How to Apply Information Architecture Principles for the Content?

Lecture 124 Structuring Data. Metadata and Taxonomies.

Lecture 125 What is Metadata?

Lecture 126 What is Taxonomy?

Lecture 127 Starting the Classification and Engaging Stakeholders

Lecture 128 Define Scenarios

Lecture 129 Visualize It!

Section 10: Additional Materials

Lecture 130 Content Management Systems (CMS)

Lecture 131 Writing Standards and Guidelines

Lecture 132 Targeting Content for Users

Lecture 133 Example work from students: Alice

Lecture 134 Example work from students: Marina

Lecture 135 Example work from students: Emily

Lecture 136 Example work from students: Marta

Lecture 137 Webinar Reply: Targeting Content for Users

Lecture 138 Webinar Reply: Targeting Content for Users - Part 2

Lecture 139 Webinar Replay: Basics of Structured Writing

Lecture 140 What is Information Architecture All About?

Section 11: Bonus Section: Quality in Software Documentation

Lecture 141 Defining the Meaning of Quality in Documentation

Lecture 142 What Will You Learn?

Lecture 143 A Definition of "Quality"

Lecture 144 What is "Quality" in Software Documentation?

Lecture 145 The Research

Lecture 146 The Results

Lecture 147 What Did People Answer?

Lecture 148 The Framework - Overview

Lecture 149 Helpful

Lecture 150 Comprehensive

Lecture 151 Searchable

Lecture 152 Visual

Lecture 153 Usable

Lecture 154 Reliable

Lecture 155 Grammatically Correct

Lecture 156 Translatable and Localization Friendly

Lecture 157 Accessible

Lecture 158 Using Appropriate Tone

Lecture 159 How to Use the Results from the Research?

Lecture 160 Bonus Lecture

Software developers who want to gain practical knowledge on how to offer help for the users of software products,Students who work on their software development projects and now struggle to create the documentation delivery for their app,If you pursue career as a technical writer, developer, architect, manager or product owner,Business analysts who want to know the basics of technical writing,Technical Writers and Information Developers