Technical Writing: How to Write Software Documentation

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!