When we think about documentation skills, the first thing that comes to mind is writing — the grammar, spelling, and sentence structuring. But who likes reading dense text?
Documentation is about communicating through various medias and finding the best way to convey an idea. And there are 5 quick skills you can learn to be better at documentation:
- Clarity, concision, and precision
- Speak the language (vocabulary)
- Interpretation & Reading Between the Lines
- JIRA and confluence knowledge
- Use of pictures
Clear, concise, & precise writing
Clear writing uses optimal vocabulary. Concise writing is short and to-the-point. Precise writing is using the right degree of detail.
I think these elements speak for themselves, but let’s look at some examples. Starting with clarity:
- Unclear: The button should be placed at the bottom.
- Clear: The programmer should place his/her “Click here” button 10px from the bottom and center it.
- That’s not the best way to tell someone how you feel, by saying it.
- Actions express feelings more effectively than words.
Concision expresses ideas in the shortest way possible:
- Not concise: Wade your way through the swamp until you reach the sandbar.
- Concise: Walk to the sandbar.
- Not concise: Click here to see more.
- Concise: More here.
Precision expresses ideas with the right amount of detail:
- Pick up that ball over there on the side.
- Pick up the white ball.
- Insert the disk and screw it in.
- Insert the sealer disk from the left, such that the 90° angle is under your chin, then screw it in with a 1 inch Phillips head screwdriver.
Writing clearly, concisely, and precisely facilitates communication and teamwork within the organization. It’s a skill you must practice. When you do, people will praise your documentation.
Speak the language (vocabulary)
When you travel to a foreign country, you don’t expect the locals to understand you automatically. Most people try to learn a few words before arriving in order to communicate with natives.
Sometimes you get lucky and come across people who will understand you speaking in English, but it’s certainly less enjoyable for them.
The message here is simple: learn to speak the business analysis language. You need to know what expressions such as “acceptance criteria,” “definitional business rule,” and “non-functional requirement” mean in order to write clearly.
The International Institute of Business Analysis (IIBA) has developed this page. You’ll see the shear magnitude of terms in the profession. Of course, you don’t need to know them all. Most disciplines have a number unused vocabulary terms.
The best way to learn what you need to know is by spending time in the profession, talking to others, and reading books about ideas. The vocabularly will then come naturally.
With that said, here’s a list of 10 phrases and words you should probably know ASAP because they’re so important.
10 Phases to Know
- Minimum Viable Product – the most rudimentary version of a product or feature that you can test live
- Functional Requirement – what the product must be able to do/perform
- Non-functional Requirement – metrics that the product must reach, not actual behaviors
- Requirement analysis – the gathering and interpretation of requirements expressed by clients, customers, or stakeholders
- Unified modeling language (UML) – a set “language” used to standardized how professionals visually represent systems
- User story/story mapping – the general path a user takes through any given system, often a sales channel from first contact to receipt of product
- Stakeholder – anyone who has a vested financial or organizational interest in a product or project
- Sponsor – a stakeholder providing guidance on a project or product
- Elicitation – the gathering of functional and non-functional requirements
- Business problem – either market, organizational, or managerial challenges that a business faces
One of the key skills in “speaking the language” is an ability differentiate between similar terms. Often the subtlety between similar words can change the meaning of a message. If, for example, you forget to put the “non-” in front of “functional requirement,” it could lead to serious confusion in your team.
Documentation Needs Data
Writing in a business context is inseparable from data. A common misconception for business analysts is that they don’t need data skills. Nothing could be further from the truth.
In order to quantity requirements, solutions, and results, BAs ALWAYS use data, so you need to have a strong understanding of the fundamentals to be successful. You can get a free copy of Intro to Data Analysis to get started strong, because you’ll need it as a BA!
Interpretation & Reading Between the Lines
In the context of business analysis, perception means understanding the difference between what people say and what they need. If you take a step back, you may realize that you do this on a daily basis. Just today, I wanted to peel an apple and asked my roommate for a knife. He laughed and handed me a peeler. Sometimes we don’t know the best tool to get the job done.
Another example of mistaking what we need is more conceptual. Let’s say you’re frustrated with a roommate for eating your food. You think you need to yell at him/her to stop. Then your landlord adds dividers in the pantry, and the roommate stops eating your food. The solution to your problem of an entirely different nature.
The same principals are at play for business analysts, but BAs are external to the problem. They need to listen to what people say and the requirements they lay out. Then they must interpret those requirements and propose their own solutions. As the saying goes: you may not give the customer want they want, but you give them what they need.
This is something that you will need to document. The more you build the skill of interpretation and perception, the more successful your documentation will be.
JIRA and Confluence, and other tools
Documentation is tough and time consuming. That’s why companies create documentation and ticketing software such as Confluence and JIRA.
These technologies are world unto themselves. It can take years to fully master them, but it’s worth it. When correctly structures in an organization, JIRA ticketing can help every team member and stakeholder better organize himself/herself. It ensures people have consistent updates on projects to avoid disruptive follow ups.
Confluence is the ultimate document-sharing technology. It operates much like the internet, but within a company. Anyone can post documentation pages, upload Microsoft documents, link to each others work, and centralize information. Because it’s within a company’s IT systems administration, latency times are low.
Learning ticketing and documentation software like this will greatly enhance your ability to deliver quality documentation, and do so quickly.
Use pictures and UML models
If you take nothing else from this article, remember to use pictures in your documentation. This is actually one of the fundamental principles of business analysis. A picture is worth a thousand words, especially when you’ve done a good job creating it.
A common tool, or language, that business analysts use to create documentation pictures is called Unified Modeling Language, like we saw above. It’s not necessarily a coding language, although you can use code to create it. It’s more often seen as a set of guidelines to follow when outlining a visual representation of a system.
Nevertheless, there are certain symbols and steps you must follow when using UML. Here’s a video to help you understand (I’m not affiliated with LucidChart).
So yes, pictures are incredibly important. You need to learn to speak the language of UML to represent systems. At the same time, you can also use simply pictures to convey messages. For example, a simply was to represent how AnalystAnswers.com is broken down is with something like this:
It doesn’t need to be fancy. You just need to get the point across. Now you know the website has articles for skills, role-specific information, domain knowledge advice, and career info.
How to improve documentation skills
You can always improve your skills by practicing, practicing, practicing. I’m the kind of person who learns by doing, so I encourage you to start writing documentation and getting feedback. If you simply want to improve, try to adhere more closely to the items discussed above.
For more ample information, take a tour through AnalystAnswers.com. We’ve got a lot of content to help you impress your colleagues, your boss, and bring true value to your organization. Our goal is for you to improve your weak points without spending thousands of dollars on certifications that won’t really help you perform better.
Conclusion
The five most important documentation skills for a business analyst are, one more time:
- Clarity, concision, and precision
- Speak the language (vocabulary)
- Interpretation & Reading Between the Lines
- JIRA and confluence knowledge
- Use of pictures
If you learn to master these skills, you will be a high performing documenter. But it would be silly to assume that these are the only skills you need to succeed. Once you improve on them, take a look at some of these documentation skills as well. You can learn about them on the website.
- Having documentation guidelines – brings consistency and clarity to the documentation structure
- Speed – documenting requirements quickly avoids miscommunication due to lacking intelligence
- Patience, Persistence, & Flexibility – being patient and persistent will help you work through what can sometimes be a tedious documentation process. Flexibility will help you when you need to make changes.
- Grammar & Spelling (Yes, you have to) – if you don’t have good grammar and spelling, it’s a recipe for miscommunication
- Fact-driven and unbiased approach – try to keep your emotions out of documentation, as it will color the way people read and understand the text
