“At the end of the day, don’t just sit back and think, what great documentation I’ve created. Instead, keep the focus on the real end game: product adoption.” Sounds like a message provoking self-analysis and lookback at all of the work you have done so far 😊
Insightful article covering the following important aspects:
- What is Markdown?
- How and where to get started with Markdown in documentation?
- What points to consider?
All things considered, let’s put it that way:
Whereas Markdown is much simpler than HTML or any other markup language, it may introduce a lot of mess to documentation with complicated structure.
On the other hand, it may be quite enough to create simple docs (like, say, Release Notes) on a project.
What do you think?
Recently, I came across the article “Seeing things from the perspective of a learner” by Tom Johnson that responded to my frequent apprehensiveness that the produced documentation would not respond to the real needs of the users it is produced for.
Very often, we start writing the documentation being a “blank page”, completely unaware of the domain and the application. And that’s when we first start hesitating whether we would be able to grasp enough information needed to make the experience of the users with the application more pleasant. We dig the technical and the domain details very deep and stop realizing that we already know too much to write the documentation that the real-life users with the real-life problems need. We forget those first “silly” questions that we once had at the beginning, and everything seems so clear to us, that we start producing the documentation that is either too hard to understand or contains too much techy details and almost no information for beginners.
Are there any tips to avoid the “curse of knowledge”? In his article, Tom Johnson shares some great recommendations:
- Take advantage of your product ignorance.
- Capture all the questions that you have while making familiar with the product.
- Refine the “dumb questions” really carefully, as further they may come in handy when structuring the documentation.
It seems, this article caught not only my attention. In his blog, Mark Baker also discusses Toms’ article and an important idea he adds is that product ignorance does not equal domain ignorance. We need to be aware of the domain as much as we can since we write the documentation for the users who are experts in this domain.
Mark adds a couple of ideas to Tom’s article, and I cannot help but agree with them:
- Domain awareness should mean knowing the whole context – not just separate subject matters.
- Domain awareness may help us understand the typical users’ pains with our product.
- Domain awareness helps us write quality and understandable documentation that explains and teaches.
- Domain awareness is a long and hard path for a Technical Writer, but still a rewarding one.
With this being said, I would also add that analyzing the users you write for (their daily routine, tasks, and troubles) is also one of crucial things to produce effective documentation, which in no way can be omitted or left out.
Sooner or later, each seasoned Information Developer starts wondering whether the quality of content produced can be measured. And so do Information Development Managers. However, in addition to content quality metrics, managers care about one more aspect—measuring the productivity of their department in order to improve and streamline their team efforts.
Thus, when thinking of developing and introducing metrics in your organization, you should think of at least two metrics to assess:
- Content quality
- Work productivity
Once you have lots of projects behind your Office’s back and a bunch of them in progress or yet to come, you start analyzing if anything could have been done better, quicker, and more efficiently.
Each documentation project is unique in its own way, but when you look closer, you can find that most of them follow processes, rules, and collaboration patterns that do not differ that much.
Therefore, we’ve built the documentation assessment process that proved its efficiency and improved the overall quality of our projects, not only at their final stage, but right from the start.
Information Developers in their work oftentimes stumble upon the cases when content creation may seem to be a much easier task than predicting how much time it would take. And usually, it happens when we are involved in a new project or in the presales activities, but it’s also a part of our routine activities on any project.
The first temptation is to use the industry averages like 4 hours per a help topic. But are you sure this will work for your project?
In the previous post, we talked about the benefits of creating a “magic pair” of Information Developers with Business Analysts. Hope that post gave you some ideas on how to organize your work environment even better to achieve top results. But don’t you stop on that! Today, I’m going to tell you about one more magic pair that deserves its place on the project – and that is the InfoDev–UX Designer pair.
Why UX Designer?
The IT industry never stops: the approaches and priorities that were popular yesterday become obsolete and out of trend today. Previously, we cared more about the quality of software and documentation. Now, we think more about what benefits this software or documentation will bring to our users and whether this software or documentation really solve day-to-day tasks of our target audience. One can definitely state that in the IT industry, the focus has shifted to the end-users.
And this shift has made IT specialists rethink the way they worked before and adapt to the new challenges.
I’d confess that previously, Information Developers (aka Technical Writers) were the advocates of the users. We constantly thought of the possible user scenarios and did our best to make lives and experiences of our users better. Today, this is not enough. Users’ habits have changed and are still changing with the speed of light; the pace of the world is changing even quicker. Everyone has become more impatient. So, very often, it doesn’t even get to documentation in its traditional meaning. Users want to get the information they need right at the very moment they need it.
At this point, you understand that the past process doesn’t work, and this is when you have to charm a bit and bring magic to your everyday work life.
The world of IT and high technologies is constantly growing and expanding its horizons. IT has immersed into our lives so quickly that we can’t imagine our daily routine without technologies anymore: mobile phones, smart watches, e-books, laptops…
And every single gadget or application has supporting documentation that bridges the gap between technology and users and makes learning curve as smooth as possible. Technology is striving to become closer to people, and Information Developers (also known as Technical Communicators or Technical Writers) are the wizards who help bridge the gap.
Is there any silver bullet or golden set of characteristics for becoming a successful Information Developer?