Faq As Documentation
Faq As DocumentationIt seems to me that a FAQ could very well be the best form of documentation for a system. -- OleAndersen
I tried this on WyCash. After answering questions or solving problems I turned to an early version of wiki and made a page about the problem-solution (See WikiWikiHyperCard). On my departure I left the company with a well written program and fifty pages of hyperlinked notes about essoteric things that didn't just jump out at you while reading the source. Later I was aked to help train some new recruits. I came in for a day to answer architectural questions. I asked if they had read the source? Yes, very helpful. And had they read the hypertext faq? Yes, not so helpful. (Not so helpful yet, I thought.) Then we talked about the source and the hypertext for an hour or so. Did they learn anything more? Just one thing: yes, they really did know the system. There isn't more to know. -- WardCunningham
p.s. I often interrupted the system and read the traceback to see what it was doing. Our architecture was so well factored that the traceback read like a document. I once wrote a document by just annotating a copied traceback. There is not much chance of doing this with java, I'm sorry to say. Oh how far we have slipped away from real object-orinted programming since this was written ten years ago.
p.p.s. WyCash is still in production generating revenue after a decade. The hypertext faq was lost with the company's eventual elimination of Macintosh computers.
There are FAQs, and then there are documentation efforts using a QA format with the word FAQ in their name. Real FAQs are answers to questions that a real forum actually frequently answers.
To be reviled are bogus FAQs containing questions the author guesses, or wishes, would be frequent. Have you ever tried to install something, got stuck on a first stupid question that should be frequently asked, surfed to the vendor's Web site, and read a FAQ where the first question was "Why is this product clearly superior to the competition's?"?
In my day, we used to call those things press summaries, which were part of press kits. Now, they are called FAQs, part of brochureware websites. Bah.
The book C++ FAQs, though its answers are excellent, falls into the hypothetical-question category. --PCP
If I recall correctly, that is an unfair characterisation of C++ FAQ's. It has been a long time since I looked at it, but isn't that the book that was built from the comp.lang.c++.* FAQ's?
I answered that newsgroup's questions for 2 years or so. But other than that I might not know what I'm talking about ;-)
EditText of this page
(last edited February 21, 2003)
or FindPage with title or text search