Documentation Design Policy, User Guide versus FAQ. James Cameron, 9th November 2001. There are two primary documents in this project, the User Guide and the FAQ. They serve different purposes. The User Guide - is the FreeTDS 'product' documentation, - is specific to each release, - is included in the release, and on the FreeTDS web site, - is structured as a HOWTO, or a list of steps, to get the software working. The FAQ - is the FreeTDS Mailing List documentation, - is FreeTDS release independent, - is on the FreeTDS web site, - is structured as a list of questions. The risks we need to address are: - duplication of content, increasing cost of maintenance, - conflicts between the documents, causing mail traffic, - outdated content is left present, causing mail traffic, - insufficient content, causing mail traffic, - too much content and too little indexing, causing mail traffic. So some policy suggestions ... The FAQ should not duplicate content found in the User Guide, and vice versa. If they have access to the FAQ, they can read the User Guide. If they have access to the User Guide, they shouldn't need the FAQ, unless they hit a defect. To avoid duplication, the FAQ should point to the User Guide to address specific questions, unless the User Guide hasn't got the answer. The User Guide should only point to the FAQ base URL, and should never need to point to specific FAQ content. New content between releases should first go into the FAQ in CVS, with an effective date and FreeTDS version number. The FAQ maintainer will then transfer this to the FreeTDS web site. This new content for the FAQ may breed code changes, or new content for the User Guide. New content for the next release should be inserted into the User Guide in CVS. Once the User Guide is released (by nature of a FreeTDS release), old FAQ entries should be reviewed. -- Date: Fri, 9 Nov 2001 08:07:18 -0500 (EST) From: Brian Bruns To: Cc: Subject: Re: FreeTDS Documentation Design Policy, Draft In-Reply-To: <3BEB6E09.9BC32E58@stl.dec.com> Message-ID: My .02$ The FAQ is 1) A brief description of what freetds is/does (for completeness) as this is the first document many people see. 2) A pointer to other resources: mailing list, user guide, CVS, protocol docs 3) what is supported/not supported. ie Do you support feature X? Including 'are you planning...?' 4) Specific known bugs/build problems with work arounds or dates of fix I think what there is good, except we need to rip out the programming section in favor of the user guide, and section 5 (CVS) needs to go under a more general 'Other Resources' section. Problems Building/Problems Running (4 & 6) probably belong next to each other. I don't know quite where to put 'Which Perl library should I use' but it seems to me to be FAQ fodder, but it doesn't fit the criteria above. The user guide is more detailed. It should explain everything you ever wanted to know about TDS/FreeTDS, discuss its many options in detail, and detail steps for building each type of configuration. I'd personally like to add a section on porting MS dblib/ODBC programs to Unix/Linux. Brian