[check] documentation additions / refactoring

There seems to have been a few discussions on the validator's 
documentation recently, I'll try and summarize what I am aware of so 
that we can improve the documentation globally, not just locally.

1- I had a discussion with Bjoern on the help&FAQ document. Bjoern 
would certainly be better at explaining his point, but his ideas were 
basically that
  * having a FAQ and a docs link in the navbar was confusing
  * help should be a help page, not a FAQ
  * mixing general, legal and technical aspects in the FAQ was not a 
good idea
  * there should be a "top validation problems" document.
	http://esw.w3.org/topic/ValidationProblems

2- Terje and Daniel Biddle (deltab) had a discussion on IRC about the 
need for a document stating what the markup validator does *not* do...
CSS, script check, link check, spell check, and other web page quality 
checks

3- the docs/ index should be made more compact for an easier global 
view of the documentation


Ideas about this. Should really be considered more as ramblings than 
actually a plan.

Solving the FAQ/document index problem. I admit the FAQ (with three 
sections on about / using / common problems) casts a big shadow on the 
documentation index, and since many have to scroll to find the links 
for the "frequently asked questions", it might not be too useful.

If we manage to improve the documentation index there should not be a 
need for two entry points to the documentation.

What are the use cases where we really want people to find the 
documentation easily? perhaps not advanced users. Some people have been 
asking for a document to link the icons from (instead of revalidation, 
which is the official use for the icons) and a section has been added 
to the help doc to help that, but not sure it's really useful.
Maybe we need to think more of all the usage scenarios for the 
documentation before revamping it.

Should "what the validator is not" be a part of "what the validator is 
(about)"?

Should we have a specific document on license, usage rights and other 
legalese fun?

More sections for the documentation? General help (help, about), Usage 
(users, favelets, accesskeys) Troubleshooting (common validation 
problems, error message explanations) Installation and development (the 
rest). Should the documentation index link to all or focus on 
introducing the most important and link to second-level docs from 
first-level docs (e.g link favelets from users, etc)?


All for now. Comments and your answers to all these questions much 
welcome, otherwise i'll just keep them here for reference and keep 
playing with the documentation until I have something I am happy with - 
no real urgency anyway.
-- 
olivier