Humanly reviewed by
Jalasoft’s own Technical Writer, Fabiola Arias, breaks down what it takes to write the best technical documentation for our clients.
Written by Fabiola Arias Navia
Every great product has a great story behind it. Not just the “founder in a garage” kind of story, but the how-to-use-this-software-without-summoning-an-ancient-curse story. That is where technical writers come in, and in this case: Jalasoft’s Information Developer Team.
The documentation process is part science, part art, and part diplomatic mission; but foremost, it is a great example of teamwork, even when some team members go unnoticed at times.
We translate developer jargon and Product Manager expertise, we anticipate user questions and customer confusion, and we distill it all into something clear, precise, and -just imagine this- enjoyable to read.
Step 1: Herding Cats, The Beginning
The first step is information gathering; think of us as coffee-fueled detectives, and reading, lots of reading.
From Product Requirements Docs and release notes, Devs and QA tickets, long e-mail threads, never-ending Slack discussions, to demos, meetings, evolving features, and some actual product testing, we will go the distance to ensure everything is tied up.
The goal: figure out what needs explaining and to whom.
In this part of the documentation process, your average technical writer asks as many questions in a day as a curious five-year-old, but with slightly better grammar… patience is required!
Step 2: Getting Our Ducks in a Row (Pun Intended)
When we have the raw material, or at least a big chunk, we start organizing it. We identify what docs will be created or updated:
- Installation Guides, from zero to hero without tears.
- User Manuals, every button explained (including the one you are not supposed to press).
- API Reference, code-level truth serum.
- New Pages Everywhere, finding surgical accuracy.
We choose formats, decide on tone, and map out the logical flow.
Step 3: Readers, Assemble! Who Are We Writing For?
Of course, we write for humans… sort of!
We draft the content in plain, concise language. We use defined alignments for this. Jargon is decoded, sentences are trimmed, and examples are added to bring concepts to life.
But what can we accomplish by doing this? Both readability and SEO (Search Engine Optimization), because good documentation is not just for people who have already found it; it is also for people who need to find it.
Step 4: The Feedback Strikes Back
Before anything goes public or, as we like to say, gets “pushed live”, it is reviewed by subject matter experts who may suggest a few adjustments or simply throw in a quick and happily received “LGTM” (which we would love to be a Let’s Get Taco Monday, but it is actually an approving Looks Good To Me).
A well-functioning review cycle can save weeks of customer support time and some serious bucks.
Step 5: Rule #1 – We Always Talk About Updates
We publish in all formats and platforms. You name it, we’ve got it. From portals, blogs, wikis, to PDFs, CHMs, and all kinds of online and offline content. But publishing is not the end: it is the beginning of updates. Products evolve, bugs get fixed, features get added, and we tweak the docs to keep pace.
While all these steps are in progress, we will also be engaged in another task: seeking ways to improve what has been done, identifying small details that may not be noticed when changed, but that will result in a stress-free user experience when following our documentation.
Final Reflection
Great documentation is invisible when it works; you follow it, get what you need, and move on. But behind every “That was easy” moment is a team of technical writers, turning complexity into clarity, one page at a time.
