Angular Thoughts on Docs
If you have visited the docs at angular.io lately, you might have noticed some changes in our content layout and structure. As the lead technical writer for Angular, I thought I’d take a moment to cover some of the main goals we have for making the Angular documentation experience the best experience possible.
Focus on developers new to Angular
A common pitfall for many documentation sets is that they address too many audiences at once. This practice results in content that is verbose, difficult to navigate, and frustrating to read. For Angular, it’s important that we focus on a single audience at a time, because we want to make sure to tell the right stories clearly and concisely. Right now, that means our documentation efforts focus on developers new to Angular.
Since I joined the Angular team, I’ve heard a recurring theme:
“Angular has a steep learning curve.”
“The Angular documentation is overwhelming.”
As someone new to Angular, I find myself agreeing with these sentiments. That’s why, for the next several months, we’re focusing on making the getting started experience the best experience possible. Some of the changes we’re making include:
- Revamping the table of contents (the lists of topics in the left navigation) to help users understand what main concepts of Angular they should understand, and what topics can wait until they want to expand their applications further.
- Categorizing topics into three topic types: Concepts, Tasks, and Tutorials. It’s important for any reader — whether they are new to Angular or not! — to know what kind of content they’re reading and whether it’s what they’re looking for. No one likes looking for how to get something done only to find themselves 3 paragraphs into a tutorial.
- Streamlining existing content. When I write, I imagine that I’m tutoring a friend who has a plane to catch in 5 minutes. This image helps me focus on content that is casual in tone, but also concise and to the point. Applying this idea to Angular documentation will help users find the information they need and get back to code.
Help users get things done
Developers need documentation for a lot of different reasons. Sometimes you need a basic walkthrough of the technology. Other times, you need a real-world tutorial that addresses a problem that you’re facing. Like focusing on a specific audience, a good documentation set focuses on one of these reasons at a time. For Angular, we’re focused on writing content that helps users get things done.
When you navigate to the Angular documentation, we want you to find the information you need to complete a task or understand a feature, and then we want you to be able to get back to writing great code. To accomplish this goal, we’re going through all of the topics to make sure they clearly state what they cover and why that’s important. You should know right away if you’re reading the content you need. And if you’re not? We’re working on providing links to other topics that might be more helpful.
Of course, there’s always a place for more conceptual content. And there’s a lot of great value in developing a deep understanding of how something works. I’m sure we’ll focus on improving our conceptual content at some point in the future. For the time being, however, we want to make sure that you can find the help you need quickly and easily.
Improve, but don’t break
As we mentioned earlier, many within the Angular community find the current documentation overwhelming. At the same time, we’ve also heard that the documentation remains one of the best places to learn how to build with Angular. That’s why one of the other key goals that we’re focusing on is to improve the documentation without breaking it. As we write new content or improve existing content, we try to make sure that the existing documentation remains intact. There are always going to be times where we might fall short on this goal. When that happens, please let us know by filing a GitHub issue so we can investigate.
Conclusion
We think that focusing on new Angular developers, writing content that helps you get things done, and making sure we improve the documentation without breaking it, will result in a better documentation experience for everyone. Of course, this is just the beginning. For example, as we wrap up content for new developers, we’ll start looking at other audiences, such as those of you working on enterprise-level applications. I can’t express how grateful I am to work on a product that has such a passionate, supportive community, and I look forward to working with all of you to make the Angular documentation the best experience possible. In the meantime, continue to check out the docs and don’t hesitate to let us know what you think!
