FAQ

FAQ

[Vincent Legoll]

Hello,

Is there a FAQ page we can contribute to ?

Something less formal than the official doc, perhaps a wiki...

-- 
Vincent Legoll

Re: FAQ

[Andreas Enge]

On Sat, Jul 16, 2016 at 03:41:43PM +0200, Vincent Legoll wrote:
> Is there a FAQ page we can contribute to ?

This is an FAQ :-)

The standard answer is that we prefer patches to the documentation instead
of spreading out the information.

Maybe we should create an FAQ with exactly this question and an answer
similar to mine?

Andreas

Re: FAQ

[Vincent Legoll]

OK, I'll try to create a FAQ section in the official doc then...

-- 
Vincent Legoll

Re: FAQ

[myglc2]

Vincent Legoll <vincent.legoll@gmail.com> writes:

> OK, I'll try to create a FAQ section in the official doc then...

Great idea!

Re: FAQ

[Andreas Enge]

On Sat, Jul 16, 2016 at 01:02:33PM -0400, myglc2 wrote:
> Vincent Legoll <vincent.legoll@gmail.com> 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.

Andreas

Re: FAQ

[Alex Sassmannshausen]

Hello,

Andreas Enge writes:

> On Sat, Jul 16, 2016 at 01:02:33PM -0400, myglc2 wrote:
>> Vincent Legoll <vincent.legoll@gmail.com> 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

Re: FAQ

[Amirouche Boubekki]

On 2016-07-16 20:15, Alex Sassmannshausen wrote:
> Hello,
> 
> Andreas Enge writes:
> 
>> On Sat, Jul 16, 2016 at 01:02:33PM -0400, myglc2 wrote:
>>> Vincent Legoll <vincent.legoll@gmail.com> 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?

+1

Focusing on the texinfo manual is not a good idea. If there is still no 
way
to make libreplanet wiki the official wiki of guix, I hope the a FAQ 
patch
can make it through

Re: FAQ

[Vincent Legoll]

I did it:
https://lists.gnu.org/archive/html/guix-devel/2016-07/msg00488.html

That's where I'm coming from with this idea of not-so-formalized, *easy*
to edit FAQ...

Something where we can tell newcomers to go wild, and ask their questions,
they don't know scheme, nor texinfo, nor should we assume anything from
them. then as questions / answers mature, they can be moved into the
relevant doc section.

That's my 2 cts

-- 
Vincent Legoll