Viết tài liệu kỹ thuật: Cách viết tài liệu phần mềm

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 follow, 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:

1. You will be able to perform the needed steps and start writing documentation as a technical writer.

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

4. You learn and practice how to create software documentation in a GitHub wiki following the instructor's templates for writing in Markdown.

5. You will know how to perform user research using 2 Cards Sorting techniques in Mural.

6. You will be able to identify the different aspects that make documentation a high-quality deliverable.

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 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 information architecture and its importance in software documentation.

• Ultimately, you will have the chance to create your own documentation project even if you have never worked as a technical writer before and have no experience.

  
  

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

JPDocu School of Technical Writing is a training company passionate about technical writing, software documentation, APIs documentation, information architecture, and DITA XML, and helping our students get started and quickly advance in their Technical Writer career.

Our Technical Writing courses are taught as a part of the University courses on Technical Communications at several universities in Europe, as well as a part of the onboarding for new technical writers for many of the best software development companies.

We shape the next generation of technical writers and information developers, by providing them with simple-to-follow and practical, hands-on experiences with technical writing.

For several years now, JPDocu School of Technical Writing has been designing and delivering training for all who want to get started with technical writing. Our students soon get started working as:

1. technical writers (information developers)

2. information architects

3. software developers 

and get ahead in their career!

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 students 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 technical writers 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 the 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 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.

Note that for better accessibility, the course comes with English and Spanish language captions.

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 materials 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. We 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, we 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 'How to Write API Documentation" course about this subject.

  
  

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

Short answer:

Section 1: Getting Started with Technical Writing - 1 hour

Section 2: Writing Software Documentation in GitHub using Markdown - 2+ hours

Section 3: Graphics in Software Documentation - 40 min

Section 4: Information Architecture Basics - 1+ hour

Section 5: Quality in Software Documentation 40+ min

Bonus Section: Additional Webinars - 3+ hours

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

Section 2:  Writing Software Documentation in GitHub using Markdown - 2+ hours

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

This section touches upon a very important subject - how to provide documentation for a GitHub project. Jordan talks about one of the possible options, and we would dare to say - the most simple one, to provide documentation in GitHub.

It will take approximately 2-4 hours to go through this content and perform the exercises.

Section 3: Graphics in Software Documentation - 40 min

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. Then we will do a hands-on exercise with Canva to prepare infographics to use in your documentation.

It will take approximately 1-2 hours to go through this content and perform the exercises.

Section 4: Information Architecture Basics - 1+ hour

Then comes the next section - on information architecture and user research 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 provides you with step-by-step instructions on how to prepare and perform card sorting workshops with end-users using a virtual whiteboard, such as Mural.

It will take approximately 1 hour to go through this content.

Section 5: Quality in Software Documentation 40+ min

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

Bonus Section: Additional Webinars - 3+ hours

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