[LLVMdev] RFC: Technical Writing FAQ (DRAFT PROPOSAL)

[Mikael Lyngvig]

Hi,

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.


Cheers,
Mikael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120616/108d1468/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: TechnicalWritingFAQ.rst
Type: application/octet-stream
Size: 7021 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120616/108d1468/attachment.obj>