5 things you can do to help Tech Writers
Hey,
You might not know, but basically everything that is developed in Liferay has gone or is going through the hands of a Technical Writer. But what does a Technical Writer do? (You might ask.)
We basically are the ones who get all the technical stuff the software engineers have written in their projects/drafts and transform that into summarized/trustworthy/credible/fancy documentation for our users and customers , or even for other developers. (Yep, we are that awesome ;)
And what can you do to help us deliver the best work possible? Here are some ideas:
1.Provide a Detailed Draft
Do we have technical knowledge? Yes. Does this mean you can write in full engineer mode, omitting parts that you think are unnecessary because “anyone surely knows about this”? NO!
We definitely spend time studying the content you’ve provided, but you are the ones who have developed the feature, therefore you are also the ones who can best describe it.
So, in your drafts, try to give as many details as you can. Provide suggestions: photos, links, videos… Even if we edit and get rid of most of that information for the final version, it is still important for us to get the bigger picture of what you are producing.
2. Show the Context in the Screenshots
Try adding the whole context in your screenshots, no matter where you create your draft (docs, word, other editors…), remember we’ll need to recreate your steps. If your photos are too focused, misplaced, or if they don’t properly represent the environment we have to document, how can we understand your feature to later explain it to potential users?
You can for example take screenshots of the whole page and add it to the draft just to show where you believe it should go, while you save the pictures in a folder so the quality of the pics are protected.
3.Provide Dummy information (Secure Private Info)
It helps, A LOT, if you provide screenshots with dummy information (e.g test@aaaaaa.com, user: test) since we have to safeguard private info. BUT… If there are specific IDs and passwords that are necessary for the features to work, please, provide those with a note, we’ll never disclose them. It’s just so we can go over the needed steps.
4.Be patient
We are going to ask (MANY) questions.
It’s basically in the job description, they only hire extremely curious people for the vacancy (é verdade esse bilete!).
It’s possible to ask the same question in lots of ways (we do that very frequently). But that’s because we want to make sure that your features have been documented as greatly as they have been developed, so do be patient with us.
5.Trust us
There are many factors that might constrict our work, like markdown that doesn’t let us open links in different tabs, or maybe it’s allowed but it would go against the company’s documentation policy.
Do you have to know all of those specificities? Of course you don’t, because that is a tech writer’s job! There is a whole team dedicated to documentation, that has constant meetings and discussions about the most different topics.
Believe me when I say that your requests, worries and concerns are not taken lightly. So please, do trust us and our work, as much as we trust yours :)
For more ideas consult your closest TW and thanks for taking interest in helping us. See you all next time \o/
