This course covers the fundamentals of writing effective software documentation. Whether you need to document requirements, architecture/design, code, test plans, or manuals for end users, this course gives you tips and best practices to do it all.
The term "technical writing" can mean many different things, depending on your field and role. But at its core, itâ€™s about communicating information. In this course, Technical Writing: Documentation on Software Projects, you'll learn how to write documentation for a software project, including requirements, the architecture/design document, code documentation, test plans and test cases, and end-user documentation. First, you'll learn how important documentation is in the world of software and how the writing process works. Then, you'll learn some tips and best practices for writing clearly and efficiently. Finally, you'll learn about common documents on a software project. When you're finished with this course, you'll have a foundational understanding of technical writing and how to communicate effectively on a software project.
Amber is a Microsoft Certified Trainer and Microsoft Certified Professional Developer with 15+ years experience working with and teaching Microsoft technologies. She also focuses on professional skills, bridging the gap between techies and non-techies. For her work as a training leader, Amber received Training magazine's 2013 Emerging Training Leader award.
Course Overview Hi everyone, my name is Amber Israelsen, and welcome to my course, Technical Writing: Documentation on Software Projects. I've been a developer, author, and technical trainer for 15+ years, and I'm very passionate about this topic. In my years working on software projects, I've found that documentation is often a dreaded task, one that gets pushed to the last minute, or overlooked completely, but good written communication skills will take you far on a software project and in life. In this course, we're going to talk about the importance of documentation in the world of software, look at the writing process, how to get information out of your head and onto paper, dig into some tips and best practices for writing clearly and effectively, and finally, examine common documents on a software project, including requirements, the design or architecture document, code documentation, test plans and test cases, and finally, end user documentation. By the end of this course, you'll have a foundational understanding of technical writing and how to communicate effectively on a software project. Before beginning the course, you should have a good command of the English language and feel comfortable with grammar, sentence structure, punctuation, and so forth. I hope you'll join me on this journey to learn how to communicate effectively with the Technical Writing: Documentation on Software Projects course at Pluralsight.
The Writing Process Hello and welcome back. In the last module, we took a high-level look at what technical writing is, its purpose, and some of the kinds of writings you might already be doing in this area. In this module, we'll take a look at the writing process. How do you plan, research, write, edit, and release your documentation to the world. If you remember from the last module, we're following Carl, a software developer at a company called Pharmalantis. Although Carl is a developer, his boss Bill has essentially told him that he'll be playing the role of technical writer on his upcoming project. And despite objections from Carl, there's no way out of it. Bill had suggested that Carl reach out to Anne for some pointers. So, we'll pick up with the story there. We see Carl crafting an email to Anne. Hi Anne, Bill mentioned you might be able to give me some writing pointers for the Pharmalantalert project. I'll set up a meeting with you this afternoon to discuss more. And then, so he doesn't go into the meeting totally unprepared, he does what all good developers do when they have a question. He Googles it, how to write technical documentation. Later that day, he meets with Anne in the conference room down the hall. Hi Carl. Good to see you. You too. Thanks for agreeing to help with this. I'm not really sure where to even start. Well, you're in luck. I've done quite a bit of technical writing so I should be able to give you some pointers. Let's start by talking about the overall process. End to end, the process usually looks something like this: plan, research, write, review/edit, and finally, launch. And depending on where you work, your company may use some variation of this process. Maybe there are different names for the phases, or maybe they're split out a little bit differently, but this is a good general model. Let's take a look at each of these phases in a little more detail.
Layout and Design Hello, and welcome back. I'm Amber Israelsen. I'm especially excited about this module on Layout and Design. You might not have been expecting a module about this in a technical writing course, but it's actually a very important part of making your documents easy to read and use, and it's kind of fun. So now that we've been through some of the mechanics and best practices of writing, we'll take a look at how to best visually present your information. Let's dive right in.
Deliverables: Requirements Welcome to this next module in the course where we start looking at common deliverables on a software project. Following the software development lifecycle, we'll start at the beginning with requirements. We'll take a look at some of the different approaches to requirements, including user stories, traditional text-based requirements, and use cases. For each we'll go through examples of how to write them effectively. But first, back to Anne and Carl who are meeting to discuss the existing documentation on the project. I was looking through some of the requirements that Justin started. They're a bit of a mess. Carl takes a look, and this is what he sees. The application will do stuff. The system will be easy to maintain. The users will love everything about the system. The system will be totally reliable. The system should be fast. The application ought to be built in a modular way. The stakeholders better provide sign-off without asking any questions. Carl sighs and silently curses Justin, who's sitting on a beach somewhere in the Bahamas at this point. Justin!
Deliverables: Design/Architecture Welcome to this module about the design or architecture deliverable. To recap where we are, we've completed the requirements phase and determined what we're building. Now it's time to actually design the system and come up with the architecture. But before we dive into that, let's check in on how things are going at Pharmalantis. We see Carl at his desk, typing away. Morning Carl. How's the Software Design Document coming along? Ummm… are we doing one of those? I think everyone on the team knows what they're doing. Besides, you know what they say about that kind of documentation… "If I'm writing documentation, I'm not writing code. " "I don't trust it. It's always out of sync with the code. " "Nobody reads documentation. " "We already know what we're doing. Why do we need to document it? " Those arguments won't work here. We will do documentation. So if you could just go ahead and get started on it, that would be great. So, Carl turns back to his computer and emails Anne for some help.
Deliverables: Code Documentation Welcome back. And thanks for sticking with me in this course. If you are a developer, I think you'll find this module particularly fun, because we get to talk about code. But before we get too far, let's do a brief recap of where we are in the overall lifecycle of a project. We started out with requirements and talked about user stories, traditional or text-based requirements, and use cases We saw the pros and cons of each, and walked through some examples. From there, we moved into design with the Software Design Document, or SDD. This is where you define the what and how of the thing you're building. It's a way to get everyone on the same page, literally, working toward a common a vision. And now we're in the development phase. Here we'll take a look at code comments, API documentation, and READMEs. Now, you could argue that some of this stuff doesn't get created until release time, such as the README, but the foundation of it starts while you're coding, so that's why we're placing it here in this module. To take you back to another diagram you're more familiar with by now, this is where we are in the overall flow of the course. So, let's get started.
Deliverables: End-user Documentation Hi, and welcome back. I'm Amber Israelsen. We're moving right along here, and we're up to our final deliverable, which is end-user documentation. And Carl is pretty happy about that. We're almost done! Excellent! Though I would say the end-user documentation is probably one of the most important parts of the documentation process. If users can't use the software, the whole development effort is kind of a waste. In the module about testing, we saw that developers frequently throw things over the fence to the testers. The same thing can happen when software is released to the end user. Here you go, good luck! And the user says, ummm, so how do you use this? And might even say, we won't accept this until we get good documentation to go with it. It does happen that the entire system will be rejected for poor documentation or no documentation, you don't want that to happen on your project. And you might be thinking, but if it's intuitive, we don't need documentation, right? Well, it depends on the audience and the scope and purpose of the software. But for this module, we're going to assume you need end-user documentation. Even if you're not writing a user manual to release with the software, it's likely that you'll be writing online help or FAQs, a troubleshooting guide, and all of those would qualify as end-user documentation as well. We'll talk about three kinds of documents. The first is the user guide or user manual. This tells the user how to install and use the software. Next, we'll cover quick reference guides, the abbreviated version of the user guide. And finally, we'll wrap up with release notes.
Conclusion and Additional Resources Hi everyone, and welcome to this final module of the course. I'm Amber Israelsen. We've come a long way and covered a lot of material. In this module, we'll cover the main takeaways from the course, and also see how Carl is getting on with his boss, Bill. Here we are in a Friday afternoon, 1:00 PM. Carl and his cubicle mates are working furiously trying to get everything done. Now the documentation is mostly wrapped up, Carl's had a chance to put some final touches on code and help out the rest of the dev team, so he's busy doing that when Bill stops by. Hi, Carl. I understand you're about done with documentation. Can I have a look? Sure. Let me grab my things and I'll meet you in the conference room. I'll ask Anne to join us as well.