Technical Writing is….
A bored activity for developers if they don’t know how to do it, but is needed, for business people is only a requirement and I think they don’t consider the real value of a good documentation.
When I stared my career as developer, I’ve used to take a look of the source code in every project, because I think the it is like a peace of art, you can see inmediatly if it is well architected and what patterns are implemented.
That was the way that I have learned to read the source code, but after many years in this industry, I understand that is the same with the documentation, it is very important to learn how to use it, it is part of that peace of art.
In this book has some obvious recomendations about techincal writting that I have already know, but I’ve consider that it is a good option if you want to improve your writting skill to create a good documentaion.
Here are some of my favourites highlights that I would like to share:
- Identify your audience and scope
- Don’t start writing until you know exactly who you’re gointg to writing for
- Always ask your self ‘what is exactly that the reader is trying to do or achieve here?’
- Give what the reader need and exactly when they need it
- Don’t use complex jargon or acronyms unless you’re absolutely certain that your audience will immediately understand them
- Never assume your readers have the same physical abilities you do
- Use measurable quantities wherever possible or appropriate
- Your reader should never have to Google to understand your writing (I’m partialy agree with this)
- Humour and geographical or cultural references are best avoided
- Avoid the passive voice and weak verbs, use active voice instead
- Keep your language as clear as possible
- Use lists to break up forbidding blocks of text
- Don’t assume you can use a graphic or image from the internet for free
- keep your writing interesting is to vary the length of sentences, a good sentence is around 15 to 25 words long
- Breaking big projects into chunks makes them less intimidating
- Delivering the finished project isn’t the end of the job
Final thought, I have spent more time documenting than coding, but I learned more documenting than coding in all my career. But I really enjoy coding than documenting.
Bye!
Este libro me ha dejado mucho que pensar y estoy agradecido por haberme topado con él, hace unos meses necesitaba tomar la decisión de continuar o dejar mi empleo.
Jaehoo Weblog 