Versión en español
Not too long ago I changed companies. I have been with that company for more than two years, and in that time you get to do a l...
For further actions, you may consider blocking this person and/or reporting abuse
I find writing documentaton very cathartic, and as someone who's get easily stressed by work I find writing documentation also helps me focus and get my thoughts and even my fears into perspective about a subject.
I once wrote a 450 page comprehensive system/app upgrade guide that was so well understood that 2 years later we found out that the app vendor's consultants were using my document "illegally" to organise and perform upgrades on all their client sites!
The one key for me when I'm wiring documentation is empathy, who am I writing this for and what's their base starting level.
I start all my documents with a declaration of what it's about, what it's *not * about and a small list of 3-5 techs you will be expected to know about, with links to other sources if you don't know them.
How long will the docs need to last ofr? Today, tomorrow, next month, next year, I've got documentation I wrote 15 years ago that's still in use.
As your English teacher taught you, "beginning, middle and end", which in tech docs should be an outline so you don't go off track and digress.
These are always my starting points.
I love writing and reading or reverse 🤣 and I love the chaotic situation when I need to focus on something that I can solved. Documentation it's like sex when is good, is very goood. When is bad is better then nothing.
And I forgot who telling me that words 🤔
Mia, that's a great article, I hope people read it and document better their thing. That's make such a difference when someone join the team for example. Reading is like telepathy.
My own tips for having more impact with documentation with less efforts
And documenting is useless if not updated regularly. It is a huge efforts maintaining the docs. Once outdated, becomes untrusted and unworthy.
I'm going to add this tip! Thanks
That's just like code.
Actually probably much less efforts than code, updating documentation is easy.
But yes, that's an important habit to have.
When someone asks me about something that's not yet in the documentation, either I update the documentation directly, or I give him the updated info and ask him to update the documentation.
I've just added your tips! Thanks
Good recommendations, but you missed the key one that everyone seems to miss:
Test your documentation!
Hopefully, no one writes code without testing it, even if only manually. And most devs have figured out now that UX means user testing – basing decisions on our own guesses is a terrible approach.
But for some reason we assume that we know instinctively, I guess, what those who read our documentation will need. That's absurd.
We should identify as many audiences as we can, prioritize them, and then test on subjects from each area. Don't assume anything.
I find this is a problem with most tutorials and teaching materials as well. I can't count the number of tutorials that have stymied me (an "expert" developer) because they forgot to mention some key fact or assumed knowledge I did not have. This has wasted literally hundreds of hours of my time ... maybe thousands over the years.
(Multiply by the number of readers to get an idea how much time and effort your failure to test your documentation has cost others.)
Test, test, test! You'll be shocked at what people take from documentation that you thought was obvious and straightforward.
That's true! I'm going to add that point