Category Technical Documentation

GitHub Edit

About Magento 2.0 developer documentation

With Magento 2 dev beta we also launch documentation in GitHub. Here is a bit more info for those interested. Hi everybody, this is Bradburn Young with a guest post. Thanks to Alan for lending me his space to talk to you here. I lead a team of technical writers here at Magento. We publish […]

Confused senior man reading assembly instructions

Answer Questions versus Writing Manuals – Why not do both!

If someone asks you how a product you are developing works, should you answer? They could ask via email, Jira issue, or in person. Is it better to shun such people, write product documentation, and tell people to go Read The Full Manual (and stop bothering you!) My preference is a combination of both. I […]

books

Documentation Sets

My last technical documentation post on remembering the audience reminded me of the importance of designing the documentation set for the product you are working on. Knowing the audience is a critical part of writing a manual. I like the approach of having a short introduction section where all manuals follow the same structure. Standard […]

learn more

Technical Documentation Writing

There are whole books written about technical documentation writing. Here are my key take aways. Make sure you know who the audience is before you write a single word. You are writing documentation for others, not yourself.  Put yourself in their shoes. Use terminology the reader will understand. Use short simple sentences. Long sentences get […]

doc-writing

Why Writing Documentation is Good for Your Career

Most programmers do not enjoy writing documentation. But did you know writing documentation can be good for your career? Here are my top reasons why: You show management you want others to understand – you don’t want to hold others back or hold the company to ransom because you are the only one who knows […]