Have you ever tried putting together an aircraft model without reading the instructions? We are not saying it is not possible, but it sure is difficult, let alone time-consuming and potentially frustrating, especially after realizing you glued the wrong parts together...
As the complexity of the use of a service or product increases, assembly instructions, user manuals, or any type of documentation for the end-user becomes more important, mostly because they accompany users when discovering the usability of a product.
These pieces of information are meant to ensure the product is used correctly or guide the users in finding the correct path when they need help.
What are The Benefits and The Value of End-user Documentation?
When customers have accessible information that helps them to answer their questions easily, the number of support calls or inquiries received decreases, improving customer satisfaction, leading to referrals, recommendations, high customer retention, and most importantly, reducing costs to the company.
Besides, the process that well-written documentation follows gives the opportunity to understand the product from a user’s perspective and helps to find flaws or any other opportunities in the product that can be improved in the future.
Among the benefits, the time invested in training processes is one worthy to mention, when a company has new employees, good documentation can help reduce the time a team invests when training these new members.
This documentation which can be user’s manuals or guides, as well as quick start guides or references, is usually written by Information Developers, more commonly referred to as Technical Writers.
To ensure high-quality documentation is important to follow a workflow that may vary on the product; however, there is a general process that is the base when creating end-user documentation:
1. Gathering information
Information Developers, also known as Info Devs need to understand and be aware of the scope and details of the new release and all its features. This information provided by the stakeholders is the kick-off for a great start, therefore, communication with stakeholders, such as Product Managers, Architects, and Developers is considered very important.
Info Devs also perform online research for information that would help consolidate their knowledge on the required subjects. Always looking for reliable sources of information.
2. Product Exploration
As development progresses and iterations are finished, new product features become available. Ideally, this part of the process requires the Info Dev to have access to development builds to install them, test, explore, verify, and reproduce features or issues. In this stage, the Info Dev gains knowledge to accurately describe the required details, from a user’s perspective.
3. Drafting documentation
The result of the previous stages becomes visible in this stage. The Info Dev must write the required documentation in the clearest, concise, and consistent manner; always aiming for accuracy and simplicity throughout her/his writing.
A valuable best practice for the Jalasoft Info Dev is proofreading. This reduces typos and unwanted mistakes and guarantees compliance with the customer’s documentation style guide.
4. Submit for revision
Once the documentation draft is ready, it is submitted to the stakeholders (PMs, Software Architects, Devs), for revision. Stakeholders should provide feedback about the overall quality and accuracy of the information.
5. Feedback
The main purpose of receiving feedback is to improve the quality of the documentation. Sometimes the approach is quite simple: the Info Dev receives suggestions and applies the changes. But sometimes it might trigger conversations that should help clarify some doubts or misunderstandings. Whichever is the case, the goal is the same: improve the quality and accuracy of the documentation being developed.
6. Final draft
After having applied the changes suggested in the feedback received, the Info Dev submits the documentation to the stakeholders once more for revision. Sometimes the revision process can go back and forth more than once. This is expected since it is a good practice to guarantee the documentation's quality.
7. Publish documentation
When documentation is approved, it means the Info Dev has the green light to make the new documentation publicly available. Publishing the documentation is usually coordinated with the Product Managers or Marketing and generally happens one day before or the same day the release is scheduled for General Availability.
One final review after the documentation is published is mandatory to verify that all the images and links are working properly. Most of the time, software documentation is published online; sometimes it is embedded in the product, and sometimes both.
Are you interested in automating documentation generation? Learn how DevOps orchestration tools can automate processes from code comments, API definitions, and configuration files.
The Nitty-Gritty of Technical Writing – Tools of The Trade
Being an Info Dev is not an easy task, many strengths are essential to this role and their daily work:
English proficiency
Communicate ideas and concepts fluently, in a clear and concise manner, as well as to exchange ideas and perceptions related to the products being documented and the technologies involved.
Technical skills
Perform basic troubleshooting tasks on the different systems/products assigned to them. Technical Writers are technologically inclined and tech-savvy enough to guarantee a correct perception of the product’s features and use, and the technologies involved.
Abstract and logical thinking
Software development per se is built on abstract concepts and non-tangible ideas. Technical Writers must be capable of decoding abstract concepts and explaining or describing them in simple terms.
The value of logical thinking resides in the ability of the Info Dev to organize the information being developed so that the end-users can benefit from it without much cognitive effort.
Attention to detail - Proofreading
Accuracy is key when developing end-user documentation. It can only be obtained through constant, detailed assessment of the information being written.
A misplaced comma can change the meaning of a sentence, that’s why proofreading is a constant for Technical Writers. Even after the documentation has been published, the Technical Writer must proofread it.
Empathy - Audience Perception
End-users can go from inexperienced or new users to experienced or advanced users. Being aware of the target audience plays a significant role in how the product documentation is written.
Digital tools proficiency
Digital tools Technical Writer uses daily include Microsoft Windows OS, Microsoft Office Suite, project/task tracking tools, Adobe Photoshop or any alternative image editing software, and online collaboration tools such as Google Docs, Sheets, and Presentations.
Basic to advanced knowledge of HTML, CSS, Markdown, Versioning process and tools, and integration procedures.
Technological adaptability - Quick learner
The ability to grasp new concepts, whether related to the technologies used in the documentation tasks or the technologies being documented, is crucial for a seamless documentation process and can become even more valuable when migrating from an in-house documentation team to an outsourced one.
Adaptive to changes
A positive attitude toward change defines a person’s capability to adapt to change. Technical Writers must have a quick adaptation response towards change, as it affects directly how fast the tasks are completed and the problems are solved.
Technical Writers at Jalasof: The Best Info Dev Squad
At Jalasoft, we built the Info Dev (Technical Writer) role from the ground up, leveraging agile nearshore methodologies. The experience obtained over the years has enabled us to foster the role and has given us the tools to overcome new challenges as they are presented. We adhere to software delivery best practices to ensure that our Info Dev (Technical Writer) teams are well-prepared to handle changes efficiently, enhancing their ability to contribute significantly to our agile software development projects.
The Info Dev Squad has gained recognition throughout the company because of their performance, and their contribution to the company’s culture. Being an Info Dev at Jalasoft is not just a role, is a brand!
Working with our on-demand Jalasoft's roles like Info Dev is an exceptional opportunity to quickly engage experienced professionals within your team and achieve success on your software programs. Thanks to their high experience, information development teams find new solutions rapidly.
If you are considering a career goal that involves rapid adaptation and finding solutions to ever-changing scenarios, consider joining us as part of the Info Dev Squad! Do not wait for more! Contact us now so you can benefit from this great opportunity! we'd love to hear from you!
Read the Best Practices for Software Project Management article if you're eager to expand your knowledge. Additionally, read What DevOps is to understand how to enhance collaboration culture.
