Udemy

Platform

English

Language

Software Engineering

Category

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!

4.04 (328 reviews)

Students

12 hours

Content

Feb 2021

Last Update
Regular Price

EXCLUSIVE OFFER
Exclusive  Offer
Unlimited access to 30 000 Premium SkillShare courses
30-DAY FREE TRIAL

What you will 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


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 you 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 about "The 20 hottest job skills companies are looking for right now"


By the end of this course:

  1. You will be able to describe the processes and principles for writing.

  2. You will be able to explain the process for preparing, organizing, and delivering software documentation for the users of software products.

  3. You will be able to create instructional images and graphics needed in your documentation.

  4. 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 is metadata and its importance in software documentation.

  • In the end, 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 been constantly evolving.

We've started as technical writers, focused solely on technical writing. We transformed into information developers, that also take into account the graphical aspects and design of the content.  Today, we need to bundle together the 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 architects

- software developers 


The instructor, Jordan Stanchev, a User Assistance Development Architect has personally trained hundreds of people in the classroom, online courses, universities, and internally at a Fortune 500 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 career using what they have learned in my courses!

That's the reason 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 samples of work that 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 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, 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 you at least 2 semesters at the university and lots of writing practice. It is not possible 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 wringing 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, 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 couple of 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.

- Some lectures do not provide a perfect audio experience. There are webinar recordings from classroom sessions, lectures recorded at different times, and using different equipment. You may hear classroom noises or imperfect audio recordings. Feel free to reach out to ask for clarifications or newer versions of particular lectures.

Still, if it is the information about technical writing that you want and you can handle non-perfect audio - this is still your course.

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


How much time will it take for you to go through this course?

Short answer:

Section 1: Getting Started with Technical Writing - 70  min

Section 2: Documentation in the Software Development World - 10 min

Section 3: Writing Software Documentation in GitHub using Markdown - 1 hour

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

Section 5: Introduction to Structured Writing - 1 hour

Section 6: The 12 Principles of Technical Writing - 1 hour

Section 7: Software Documentation Development using DITA XML in Oxygen Author - 1 hour 30 min

Section 8: Using Graphics and Images in Software Documentation - 1 hour

Section 9: Strategies and Information Architecture - 40 min

Bonus Content: Webinars - 60 to 90 min per webinar in this section


Detailed answer with explanation:

Section 1: Getting Started with Technical Writing (as a compliment for 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 the technical writing skills and techniques. This is the software documentation, images as well as instructional videos, and multimedia.

It could take you 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 hour

How to get started writing in a wiki in GitHub? This section explains the setup steps, 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 in wiki

- how to create a Table of Content (TOC) for your longer pages

- how to link a YouTube video with ease

This section touches upon a very important subject - how to provide documentation for a GitHub project. I talk about one of the possible options, 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 hour

Have you ever wondered how successful software development companies bring a holistic user experience with their products? After all, companies like Apple, SAP, Oracle, VMWare - they all 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 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 a style guide in your company?


Section 5: Introduction to Structured Writing - 1 hour

How 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 see already 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 min

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

How 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 you approximately 1-2 hours to go through this content and perform the exercises.


Section 9: Strategies and Information Architecture

Then 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) need to have to begin doing his or her job. This section is more like an overview of the metadata concepts and possible scenarios that 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: Webinars

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

Here is what students say:


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 for your customers!


P.S. This course comes with a 30-day full refund policy - no questions asked!


Screenshots

Technical Writing: How to Write Software Documentation
Technical Writing: How to Write Software Documentation
Technical Writing: How to Write Software Documentation
Technical Writing: How to Write Software Documentation

Content

Getting Started with Technical Writing

What Will You Learn?

What is Technical Writing?

Who is Doing Technical Writing?

What is the Result from Technical Writing?

The Job of the Technical Writer

What is Software Documentation?

Technical Writers in the Software Development World

Technical Writing Deliverables for Software

Documentation in the Software Development World

What Will You Learn?

Technical Writer in the Software Development Team

The Technical Writing Process

First Exercise

The Ultimate Purpose of the Technical Writer

Principles of Technical Writing

Principles of Technical Writing

Basics of Structured Writing

Targeting Content for Users

Writing Standards and Guidelines

Content Management Systems (CMS)

Checklist for Developing User Assistance

Check your knowledge

Software Documentation in Oxygen Author

Writing Your First DITA Documentation Using Oxygen Author Tool

Writing Documentation using Oxygen Author DITA CMS

Software Documentation in GitHub

Getting Started with GitHub Wiki

What is Covered in this Section? First Exercise!

Writing Documentation in GitHub

Writing Using Templates in the Wiki. Create a Page Using a Template

Benefits from Working in this Section on GitHub

Using Graphics and Images in Software Documentation

Introduction & Materials to Download for This Section

Agenda

Why Graphics are Important?

When to Use Graphics in Software Documentation?

Types of Graphics in Software Documentation

Accessibility of Graphics

Using Appropriate Colors

Typography

Style Guide

Translation Aspects

Exercise - Step 1 - Introduction

Exercise - Step 2 - Demo of Tool 1

Exercise - Step 3 - Demo of Tool 2

Strategies and Information Architecture

What is Information Architecture?

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

Why Should I Care About Information Architecture?

Information Architecture in Technical Writing

How to Apply Information Architecture Principles for the Content?

Structuring Data. Metadata and Taxonomies.

What is Metadata?

What is Taxonomy?

Starting the Classification and Engaging Stakeholders

Define Scenarios

Visualize It!

Final Assignment

What's New?

Release Notes

Bonus Section

Webinar Replay: Basics of Technical Writing

Webinar Replay: Principles of Technical Communications

Webinar Reply: Targeting Content for Users

Webinar Reply: Targeting Content for Users - Part 2

Webinar Replay: Basics of Structured Writing

Information Architecture for Technical Writers: Taxonomies

Congratulations! You are at the end of the training!


Reviews

P
Paul28 May 2020

The course content and tutor are great but the audio is shockingly bad. I have an 800 watt Amp that I worryingly had to turn up extremely loud in order to hear whole sections of this course. I say I was worried because in any notification came thru on my PC at the same time it was painfully loud. Good luck if trying to complete this course on a laptop. Its a shame because the presenter is great.

F
Franz-Josef6 December 2019

Will not even skim through a course in which the instructor didn't check the section headings (see section 20 and 21, second time he writes "DITA CMS" instead of "Author Tool") or presents unreadable tables (see section19). Sorry, that is not enough. Will refund this.

E
Erika14 August 2019

It is just the instructor talking. According to the description the first section should take an hour and a half becuase there are exercises and additional material. It took 20mins - no mention of exercises or where to get additional material from.

G
Grace7 August 2019

Great course, very informative and exceeds my expectations! This course also offers exposure to a variety of relevant tools I did not know exist. I appreciate that the instructor took the time to improve the quality of audio in the first section. It's also worth checking the volume of the audio from Section 6 onwards - not sure if it is just me but even when I set the volume to the highest, it's still below my preference (unlike the earlier sections).

D
Dzvinka1 August 2019

This course provides a lot of information and the content is relevant. That is something valuable to me. Nonetheless, there are two reasons why I am not quite satisfied. First, inconsistent volume. Each video has its own loudness and it is very distracting to constantly regulate it. Second, the delivery of the material. The instructor sounds rather monotonous and it's difficult to follow him, especially when the videos last longer than 20 minutes.

A
Anita28 July 2019

Course relies heavily on the presenters voice (few helpful visuals). The presenter has a very "thick" English accent and often stumbles over his words. I've had to rely on the captions, and sometime the captions haven't been of much help either. When visuals are used, sometimes they're helpful, but more often they're distracting (text slides need to be split into multiple slides, rather than a big body of text. I often find myself trying to find the points the presenter is talking about in the body of text.) Quiz at end of section one questions content that is only addressed in the next section. Unit 17 has been copied from another text file, but the layout in Udemy is broken (the layout is terrible). I printed the first printable resource (unit 3), but I didn't print any of the later resources (I looked at them and found them unhelpful. Unfortunately the first resource print out wasn't significantly better). The above is just to mention a few frustrations I had with the course. I started this course looking forward to learn. I did get some worthwhile content, but unfortunately overall I was disappointed with the course.

H
Harish11 July 2019

Ironic that a course about conveying information would not do a good job at conveying information. And the tech problems (particularly sound) were very frustrating.

C
Chitra3 July 2019

I have incurred lot of indepth insights in this course so far. This course also provides so much resources and guidance and I am able to track my progress with effectiveness

Y
Yannick27 May 2019

Enjoyed the course but the only issue I had was that the audio in some of the videos was too low, other than that great stuff!

B
Boris13 May 2019

Interesting and detailed information about technical writing process and related software tools and best practices! I would recommend for everyone starting with, or interested about user assistance developer and technical writer profession ...

C
Chrisna9 May 2019

This was a very informative course on Technical Writing and Technical Communication on a whole. Thanks, Jordan for sharing your years of experience. Also taking the time to give feedback on work delivered. One thing, the sound on some of the clips were bad. It might be an option to add subtitles to these (#38 - 50 and #56)

G
Graham7 May 2019

It's a very good overall course. Some mis-match between the workbook that is downloaded and what you're actually doing in the course. For me the course seemed to be in two parts. The first five sections, which covered the basics and seemed to use the workbook a little. The first lecture asked us to write in the workbook, but the workbook was not available until Section 3. The bonus material in Section 7 used the workbook much more. For me this section was not bonus, it was where the real course took place - so I felt cheated. I had a certain amount of time set aside to do the course, and the final section actually took more time that the previous six sections.

N
Nikolay3 March 2019

I am extremely happy with this course! I feel much more confident in writing technical documents after taking it. The course is well structured and easy to follow. Thank you for sharing your professional knowledge in technical writing. I am looking forward to your next class, "how to write using DITA XML".

P
P.8 February 2019

I am enjoying the content. I don't know yet whether it is a good match for me and what I want to learn.

D
David13 December 2018

It needs to be more interactive from the beginning; there is too many written pages and cute pictures. I can understand the instructor, but I'd prefer a native English speaker given the majority of technical writing in the world is English. Thanks.


1315060

Udemy ID

8/7/2017

Course created date

7/11/2019

Course Indexed date
mybrain2012
Course Submitted by

Twitter
Telegram