Re: FAQ

[Alex Sassmannshausen]

Hello,

Andreas Enge writes:

> On Sat, Jul 16, 2016 at 01:02:33PM -0400, myglc2 wrote:
>> Vincent Legoll <address@hidden> writes:
>> > OK, I'll try to create a FAQ section in the official doc then...
>> Great idea!
>
> Hm, lest I be misunderstood: The aim is that reading the manual should
> be sufficient. If there is a frequently asked question, it should not
> be added to an FAQ section, but the section of the documentation where
> the question should be answered should be updated.
>
> My reply was half meant as a joke. And half seriously: As a little joke
> we could add an FAQ with only one question: "Where is the FAQ?" and the
> answer "There is none, if you find the documentation is lacking, please
> submit a patch to improve this manual." or the like.

hmm… I sympathise strongly with the notion of contralising documentation
as much as possible.  It strikes me that an FAQ is meant to do something
else from a manual though: whereas a (reference) manual is meant to be
as comprehensive and detailed as possible, an FAQ can provide
high-level, short responses to common questions.

Because Guix is relatively unique in its approach to package management,
it may well be worth trying to address some high level questions in an
FAQ, which in turn might link to the relevant sections of the manual for
more detail.

I don't know if this is the right way to go, but I'd be interested in
seeing a (patch) proposal for such a type of FAQ as an appendix to the
manual if this was what was indeed intended.

WDYT?

Alex