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 think product documentation is a good thing. I like the practice of answering questions with references to the documentation. If they come back saying they don’t understand, rather than writing a long email reply, fix the documentation instead and point them at the new version. That way your effort helps the next person as well. If you just write an email reply you have only helped one person and you may have to answer the same question again.

Stack Overflow is an interesting alternative model – questions and answers are both visible and searchable. I think while useful, I prefer the model of documentation being able to answer the questions without someone having to go look. Stack Overflow seems useful for the complex edge cases. I don’t think it should be an excuse for documentation to not explain the product fully.

I mentioned in a previous post about I was having a play with Markdown. Markdown is supported by a number of tools, including Github. (E.g. create a README.md file in a directory and Github will show it nicely formatted when you navigate to that directory.) Well it turns out Doxygen understands Markdown as well. So you can write manuals in Markdown format, commit it to GIT, and turn it into a manual (in HTML, RTF, and Latex). Cool! Even better, you can include JavaDoc from your Java code and have references from the manuals directly into the class documentation! Super cool!  (I am going to leave some unfortunate pain here for PHP until a later post.)

Bottom line: there are some good free tools around.  Using Markdown with Doxygen can be used to create pretty decent looking documentation, with pretty decent automatic formatting just by browsing the repository on GitHub with a web browser, or by using Doxygen to build a documentation set for online viewing.  If you use any of these tools, there really is not a good reason to not respond to questions with updates to the manuals, especially if all it takes is a git push to get your new documentation to your customers.