User Documentation - It is Tough

I am going to be occupied with an interesting task in the coming days, since I offered to review and improve the docs of Carbon components.

My experience is that, software engineers, specially those who are in open source arena, do not like docs that much. Even if they might consider working on design docs an important task, writing user oriented docs is given less prominence.

It is not that easy to write a good doc, targeted to a user, specially if you are a software engineer. This is mainly because, we forget that the user is new to the concepts, and we tend to make assumptions to start with. Writing the book and going through the comments made by the tech editor on the content that I wrote made me realize that as a person who is familiar on software concepts, I tend to make assumptions on the reader, that sometimes are very unreasonable.

So with that learning point, when I read a user oriented doc, I tend to ask very basic and obvious questions from myself, putting me in the shoes of a dummy user. That helps me write more user friendly docs.