16 Jun 2012 03:27
RFC: Technical Writing FAQ (DRAFT PROPOSAL)
Mikael Lyngvig <mikael <at> lyngvig.org>
2012-06-16 01:27:55 GMT
2012-06-16 01:27:55 GMT
I've put together what I think is a quite excellent beginning on a technical writing FAQ for the LLVM project. The reason I think it is quite excellent is that it does precisely what a FAQ is supposed to: Lifts the user as high up (in terms of knowledge and understanding) as possible with the least amount of text to read.
I would like to encourage you guys to rethink your "its all in the manuals" strategy and perhaps open up for letting me put together a number of FAQs about all sorts of issues that relate to LLVM and Clang. In my experience, people solve their problems by searching on Google. And they don't search for manuals but for StackOverflow.com style questions and answers. That's what makes people able to move on quickly, instead of forcing them into reading a 200 page manual only to get an answer to something that 2000 souls have already searched for an answer to. Incidentally, I LOVE writing FAQs because the more you understand about the problem at hand, the better the FAQ you make. FAQs are sort of Makefiles intended for a human reader. Lovely stuff! I am considering to make an unoffical LLVM FAQ website, perhaps together with a wiki, as I strongly disagree on the current "its all in the manuals" strategy. We live in 2012. Nobody has time to read a manual from cover to cover, unless they're very lucky or they are out of work.
Any and all comments are welcome. If you dislike this FAQ, don't hesitate to say it. I always try to work from the starting point that the user knows next to nothing because everything else is assuming that the user knows a lot (about your particular know-how) and if the user knew a lot about your particular know-how, he or she wouldn't be wasting his or her time on FAQs, but would rather be using the manuals as a reference.
Some might argue that the FAQ is somewhat redundant in what it tells the user. My observation has been that when you want to teach people something, practical redundancy is an asset, not a liability. In other words: If it makes sense to repeat something to make life simpler for the user, do so. Otherwise the user has to be very, very lucky in finding the exact right spot in all of your documentation for each and every thing you are trying to teach him or her.
To read this PROPOSAL, copy it into the llvm/docs directory and type "make html". It will then be converted to HTML, which can be read by opening llvm/docs/_build/html/TechnicalWritingFAQ.html, assuming you've got Sphinx installed.
_______________________________________________ LLVM Developers mailing list LLVMdev <at> cs.uiuc.edu http://llvm.cs.uiuc.edu http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev