Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Joachim Schiele]

glad to hear that! ;-)

On 28.11.2015 02:07, Anand Patil wrote:
> I did, and it's a terrific resource for learning the Nix language. In my
> experience, the pills were helpful at an earlier stage. Before writing
> any Nix myself beyond copying & pasting into my configuration.nix, I
> needed to develop a basic understanding of how NixOS works & how to use it.
> 
> On Sat, Nov 28, 2015 at 12:12 AM Joachim Schiele  > wrote:
> 
> did you have a look at https://nixcloud.io/tour/?id=1 already?
> 
> On 27.11.2015 22:40, Anand Patil wrote:
> > Hi everyone,
> >
> > I've been learning NixOS over the last few days, and Luca Bruno's
> NixOS
> > pills
> > series,
> 
> http://lethalman.blogspot.com/2014/07/nix-pill-1-why-you-should-give-it-try.html
> ,
> > have helped me progress much more quickly than I would have done
> without
> > them.
> >
> > It took me a surprisingly long time to find them, though. When I
> google
> > 'NixOS tutorial', they don't even make the first page. I would like to
> > suggest blessing them as an official tutorial, or increasing their
> > visibility to beginners by other means.
> >
> > Anand
> >
> >
> >
> > On Wed, Nov 25, 2015 at 3:28 PM Vladimír Čunát  
> > >> wrote:
> >
> > On 11/25/2015 02:48 PM, Rok Garbas wrote:
> > > word! we need more content not more tools.
> >
> > Better not in MS Word, but I should be able to convert even
> that ;-)
> >
> >
> > ___
> > nix-dev mailing list
> > nix-dev@lists.science.uu.nl
> 
>  >
> > http://lists.science.uu.nl/mailman/listinfo/nix-dev
> >
> >
> >
> > ___
> > nix-dev mailing list
> > nix-dev@lists.science.uu.nl 
> > http://lists.science.uu.nl/mailman/listinfo/nix-dev
> >
> 
> 
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl 
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
> 


-- 
Joachim Schiele

blog: http://blog.lastlog.de
wiki: http://lastlog.de
jabber: j...@jabber.ccc.de
GPG: C6AC8770



signature.asc
Description: OpenPGP digital signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Anand Patil]

I did, and it's a terrific resource for learning the Nix language. In my
experience, the pills were helpful at an earlier stage. Before writing any
Nix myself beyond copying & pasting into my configuration.nix, I needed to
develop a basic understanding of how NixOS works & how to use it.

On Sat, Nov 28, 2015 at 12:12 AM Joachim Schiele  wrote:

> did you have a look at https://nixcloud.io/tour/?id=1 already?
>
> On 27.11.2015 22:40, Anand Patil wrote:
> > Hi everyone,
> >
> > I've been learning NixOS over the last few days, and Luca Bruno's NixOS
> > pills
> > series,
> http://lethalman.blogspot.com/2014/07/nix-pill-1-why-you-should-give-it-try.html
> ,
> > have helped me progress much more quickly than I would have done without
> > them.
> >
> > It took me a surprisingly long time to find them, though. When I google
> > 'NixOS tutorial', they don't even make the first page. I would like to
> > suggest blessing them as an official tutorial, or increasing their
> > visibility to beginners by other means.
> >
> > Anand
> >
> >
> >
> > On Wed, Nov 25, 2015 at 3:28 PM Vladimír Čunát  > > wrote:
> >
> > On 11/25/2015 02:48 PM, Rok Garbas wrote:
> > > word! we need more content not more tools.
> >
> > Better not in MS Word, but I should be able to convert even that ;-)
> >
> >
> > ___
> > nix-dev mailing list
> > nix-dev@lists.science.uu.nl 
> > http://lists.science.uu.nl/mailman/listinfo/nix-dev
> >
> >
> >
> > ___
> > nix-dev mailing list
> > nix-dev@lists.science.uu.nl
> > http://lists.science.uu.nl/mailman/listinfo/nix-dev
> >
>
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Joachim Schiele]

did you have a look at https://nixcloud.io/tour/?id=1 already?

On 27.11.2015 22:40, Anand Patil wrote:
> Hi everyone,
> 
> I've been learning NixOS over the last few days, and Luca Bruno's NixOS
> pills
> series, 
> http://lethalman.blogspot.com/2014/07/nix-pill-1-why-you-should-give-it-try.html
>  ,
> have helped me progress much more quickly than I would have done without
> them.
> 
> It took me a surprisingly long time to find them, though. When I google
> 'NixOS tutorial', they don't even make the first page. I would like to
> suggest blessing them as an official tutorial, or increasing their
> visibility to beginners by other means.
> 
> Anand 
> 
> 
> 
> On Wed, Nov 25, 2015 at 3:28 PM Vladimír Čunát  > wrote:
> 
> On 11/25/2015 02:48 PM, Rok Garbas wrote:
> > word! we need more content not more tools.
> 
> Better not in MS Word, but I should be able to convert even that ;-)
> 
> 
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl 
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
> 
> 
> 
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
> 


___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Anand Patil]

Hi everyone,

I've been learning NixOS over the last few days, and Luca Bruno's NixOS
pills series,
http://lethalman.blogspot.com/2014/07/nix-pill-1-why-you-should-give-it-try.html
,
have helped me progress much more quickly than I would have done without
them.

It took me a surprisingly long time to find them, though. When I google
'NixOS tutorial', they don't even make the first page. I would like to
suggest blessing them as an official tutorial, or increasing their
visibility to beginners by other means.

Anand



On Wed, Nov 25, 2015 at 3:28 PM Vladimír Čunát  wrote:

> On 11/25/2015 02:48 PM, Rok Garbas wrote:
> > word! we need more content not more tools.
>
> Better not in MS Word, but I should be able to convert even that ;-)
>
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Nikki A.]

Perhaps this could work even nicer with literate programming. Source 
files could be then exported as manual chapters or extra reference, and 
the source code displayed next to text would fill gaps for curious 
readers without having to search github or download a whole nixpkgs 
repository. That would be even more awesome if some automatic two-way 
hyperlinking with usage sites could be implemented, as in a code browser 
- but I don't know if tools that good exist.

PS. Hi, this is my first message here; I'm just learning and playing 
with Nix and passing by in search for more info :)

On 18.11.2015 16:00, Augustin Borsu wrote:
> What about having a documentation field in pkgs that allows for markdown?
> Can't get closer to the code than that.
>
> Also generating an html doc of all the options of a package,
> their default value and maybe a comment by the author of the package
> and an example config would go a lng way.
>
> Le 18/11/15 15:04, Hajo Möller a écrit :
>> As mentioned in another thread, Rok Garbas proposed to remove the wiki
>> and replace it with "real documentation". I fully support this.
>>
>> To follow up on this proposal I suggest we decide what real
>> documentation should look like, so let us reiterate his main points:
>>
>> "Why do we write documentation?"
>> Is it just to remind ourselves about details, or also for helping the
>> readers reach an advanced level of understanding? It should be the both.
>>
>> "There needs to be a clear definition of how documentation is written."
>> We already have coding conventions, but there is no clear how-to for
>> writing good documentation. Maybe (professional) technical writers can
>> chime in here?
>>
>> "Documentation should teach, not tell."
>> As Rok said, handing somebody who is learning a new language a
>> dictionary would not help them learn.
>> It is not possible for us to get an immediate reaction to pinpoint the
>> exact moment our documentation becomes incomprehensible, having our
>> documentation follow a well-defined pattern should help here.
>> This also means we need to hold our users' hands, leading them
>> step-by-step through complex procedures instead of directly presenting
>> results.
>>
>> "You should never tell somebody to read the source."
>> Even though the source code should be self-explanatory (and often is,
>> see the files in nixpkgs/lib for well-commented examples), having real
>> documentation in the form of a manual helps keep everything in the same
>> place. This way there can be a single location where users come to when
>> they are lost.
>>
>> "The manual is good, but not made for beginners."
>> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
>> Although I generally agree, I am not sure where to place those tutorials
>> and what they should cover. Should they be on people's blogs, aggregated
>> in the planet.nixos.org?
>>
>> "Let's kill the wiki, it's not documentation but an abomination."
>> Unmoderated wikis tend to contain outdated or just plain wrong
>> information, it is then arguably better to have no documentation at all
>> than a wiki teaching the wrong things. Also, developers asking (possibly
>> misunderstanding) users to fix the wiki could lead to a scenario where
>> the blind lead the blind.
>>
>>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Vladimír Čunát]

On 11/25/2015 02:48 PM, Rok Garbas wrote:
> word! we need more content not more tools.

Better not in MS Word, but I should be able to convert even that ;-)




smime.p7s
Description: S/MIME Cryptographic Signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Vladimír Čunát]

Hey, everyone, please,
submit the new high-quality docs in whatever format you like best
(sounds like there will be tons of it). After reviewing the *content*, I
will convert them myself (to docbook) and integrate into what we have.
(/cc @vcunat for that)

Vladimir




smime.p7s
Description: S/MIME Cryptographic Signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Profpatsch]

On 15-11-24 09:14pm, zimbatm wrote:
> Please no XML as the source, it adds way too much emphasis on the structure
> instead of the content.
> 
> Asciidoc is pretty good. It can be configured quite close to markdown
> 
> and supports all the nice things that you need for bigger documents like
> TOC, includes, simple macros and list definitions, ...

Not sure how you got from zeal to asciidoc, but two things:

1. The nix documentation is already XML (docbook)
2. Most (if not all) languages export their documentation as HTML

What are your proposals, convert all that to asciidoc? How? Why?

-- 
Proudly written in Mutt with Vim on NixOS.
Q: Why is this email five sentences or less?
A: http://five.sentenc.es
May take up to five days to read your message. If it’s urgent, call me.
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Rok Garbas]

Quoting Vladimír Čunát (2015-11-25 14:33:41)
> Hey, everyone, please,
> submit the new high-quality docs in whatever format you like best
> (sounds like there will be tons of it). After reviewing the *content*, I
> will convert them myself (to docbook) and integrate into what we have.
> (/cc @vcunat for that)
> 
> Vladimir

word! we need more content not more tools.


--
Rok Garbas - http://www.garbas.si


signature.asc
Description: signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Matthias Beyer]

On 25-11-2015 14:33:41, Vladimír Čunát wrote:
> Hey, everyone, please,
> submit the new high-quality docs in whatever format you like best
> (sounds like there will be tons of it). After reviewing the *content*, I
> will convert them myself (to docbook) and integrate into what we have.
> (/cc @vcunat for that)
> 
> Vladimir
> 

I'm currently writing a blog post how to configure vim in
configuration.nix with vim_customizable and be able to replace vim
with neovim with the same setup. I hope this can go into the docs,
I'll notify you asap I'm done.

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[zimbatm]

Please no XML as the source, it adds way too much emphasis on the structure
instead of the content.

Asciidoc is pretty good. It can be configured quite close to markdown

and supports all the nice things that you need for bigger documents like
TOC, includes, simple macros and list definitions, ...

On Tue, 24 Nov 2015 at 15:02 Emmanuel Surleau 
wrote:

> To generate docsets for zeal: https://kapeli.com/docsets
>
> On Tue, Nov 24, 2015 at 3:25 PM, Matthias Beyer 
> wrote:
>
>> On 24-11-2015 15:00:33, Profpatsch wrote:
>> > On 15-11-23 08:03pm, Jan Malakhovski wrote:
>> >
>> > I thought about this in the past, as a first step it would be a killer
>> > feature to be able to use the documentation on the system with
>> > https://zealdocs.org/ (as compared to using the outdated versions
>> provided
>> > by default).
>> >
>>
>> While I consider zeal a really great idea, I would like to note that
>> plain-text access is essential. I don't know whether this is possible
>> if we ship documentation through zeal and even if it is possible: Is
>> it still readable? I don't know anything about the formats zeal uses.
>>
>> The proposal I filed for compiling markdown sources from the nixpkgs
>> repository into pdf or html could be used for shipping documentation
>> with zeal, if zeal is able to include the html I generate with pandoc,
>> right?
>>
>> --
>> Mit freundlichen Grüßen,
>> Kind regards,
>> Matthias Beyer
>>
>> Proudly sent with mutt.
>> Happily signed with gnupg.
>>
>> ___
>> nix-dev mailing list
>> nix-dev@lists.science.uu.nl
>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>>
>>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Matthias Beyer]

On 24-11-2015 15:00:33, Profpatsch wrote:
> On 15-11-23 08:03pm, Jan Malakhovski wrote:
> 
> I thought about this in the past, as a first step it would be a killer
> feature to be able to use the documentation on the system with
> https://zealdocs.org/ (as compared to using the outdated versions provided
> by default).
> 

While I consider zeal a really great idea, I would like to note that
plain-text access is essential. I don't know whether this is possible
if we ship documentation through zeal and even if it is possible: Is
it still readable? I don't know anything about the formats zeal uses.

The proposal I filed for compiling markdown sources from the nixpkgs
repository into pdf or html could be used for shipping documentation
with zeal, if zeal is able to include the html I generate with pandoc,
right?

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Emmanuel Surleau]

To generate docsets for zeal: https://kapeli.com/docsets

On Tue, Nov 24, 2015 at 3:25 PM, Matthias Beyer 
wrote:

> On 24-11-2015 15:00:33, Profpatsch wrote:
> > On 15-11-23 08:03pm, Jan Malakhovski wrote:
> >
> > I thought about this in the past, as a first step it would be a killer
> > feature to be able to use the documentation on the system with
> > https://zealdocs.org/ (as compared to using the outdated versions
> provided
> > by default).
> >
>
> While I consider zeal a really great idea, I would like to note that
> plain-text access is essential. I don't know whether this is possible
> if we ship documentation through zeal and even if it is possible: Is
> it still readable? I don't know anything about the formats zeal uses.
>
> The proposal I filed for compiling markdown sources from the nixpkgs
> repository into pdf or html could be used for shipping documentation
> with zeal, if zeal is able to include the html I generate with pandoc,
> right?
>
> --
> Mit freundlichen Grüßen,
> Kind regards,
> Matthias Beyer
>
> Proudly sent with mutt.
> Happily signed with gnupg.
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Profpatsch]

On 15-11-23 08:03pm, Jan Malakhovski wrote:
> That is, I'd like
> 
> * All the docs to be available and discoverable locally.
>   /run/current-system/sw/share/doc FTW. (easy to do)

Yes, please.

> * To have a thing that indexes all the man, info and haddock pages for
>   full text search using e.g. Xapian lib. (I don't know a good tool for
>   this, I'd like to get suggestions.) This can become a killer feature,
>   think universal `help` command that works faster than google (local
>   Xapian is extremely fast, as witnessed by `notmuch` and `mu`), that
>   gives matches relevant to your system, and doesn't leak your interests
>   for all the Internet to mine.

Even more yes, please.

I thought about this in the past, as a first step it would be a killer
feature to be able to use the documentation on the system with
https://zealdocs.org/ (as compared to using the outdated versions provided
by default).

> * NixOS documentation to be available in `info` format since `info` has
>   index support, indexes are awesome, and navigation in `info` is kind
>   of cool too (especially compared to plain HTML). (Should be possible
>   with docbook2x-texi)

Is info still the best documentation format we’ve got? Interesting.

-- 
Proudly written in Mutt with Vim on NixOS.
Q: Why is this email five sentences or less?
A: http://five.sentenc.es
May take up to five days to read your message. If it’s urgent, call me.
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Jan Malakhovski]

I'm in support of killing wiki and writing docs in anything except
docbook.

As a side note, just want to mention that it seems to me that a lot of
people go for google/duckduckgo/whatever when searching stuff, where as
we have at least `man -k` and `man -K`, `info -k` (e.g. try `info -k
'$!'` and then `info --index-search='$!' bash`, yep, this is not ideal,
but kinda ok with an alias), `nixos-help`, and local `haddock` and
`hoogle` databases.

That is, I'd like

* All the docs to be available and discoverable locally.
  /run/current-system/sw/share/doc FTW. (easy to do)

* To have a thing that indexes all the man, info and haddock pages for
  full text search using e.g. Xapian lib. (I don't know a good tool for
  this, I'd like to get suggestions.) This can become a killer feature,
  think universal `help` command that works faster than google (local
  Xapian is extremely fast, as witnessed by `notmuch` and `mu`), that
  gives matches relevant to your system, and doesn't leak your interests
  for all the Internet to mine.

* NixOS documentation to be available in `info` format since `info` has
  index support, indexes are awesome, and navigation in `info` is kind
  of cool too (especially compared to plain HTML). (Should be possible
  with docbook2x-texi)

  Actually, if one were to extract 240KB `info` binary from 10MB
  `texinfo` package it would, in my view, become be preferable to 1.4MB
  `w3m` binary from 3.6MB `w3m` package currently used to display the
  manual in installation images. Just saying.

Cheers,
  Jan
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Anderson Torres]

Can we maintain the wiki as an unofficial documentation? For some
small hints and workarounds, it can be useful.

2015-11-21 18:21 GMT-02:00 Profpatsch :
> On 15-11-19 05:17pm, Cillian de Róiste wrote:
>> 2015-11-19 16:57 GMT+01:00 Profpatsch :
>> > On 15-11-19 02:56am, Roger Qiu wrote:
>> > May I humbly suggest http://stevelosh.com/blog/2013/09/teach-dont-tell/ as
>> > a general documentation writing template?
>>
>> I'm a big fan of https://jacobian.org/writing/great-documentation/
>
> Yes, that’s what sjl references in the prior reading section as well.
> These two are basically the technical writing 101 everyone should know.
>
> --
> Proudly written in Mutt with Vim on NixOS.
> Q: Why is this email five sentences or less?
> A: http://five.sentenc.es
> May take up to five days to read your message. If it’s urgent, call me.
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[dieter]

hi all,
may i add that i rand into some pitfalls when learning nix/nixos when i used 
information from wikis and blogs.
as nixos is quite young and still in flux, most of the information is only 
appropriate to a certain range of nix versions.
for the case of the wiki, if it shall be kept, a simple method to avoid these 
pitfalls would be that it should be mandatory
to declare the version of nix/nixos when writing/modifying a wiki entry.
regards,
dieter
this is my first post here. 
i am quite new to nix/nixos and am fascinated by the concepts.
mostly, i am interested in bringing a machine up to a certain, well defined, 
state in a reproducible manner.
colleagues usually do this by hand-tuning a machine until it fits, and then 
clone, which always seemed awkward
to me. well.
Am Mo., Nov. 23, 2015 10:51 schrieb Anderson Torres :
Can we maintain the wiki as an unofficial documentation? For some
small hints and workarounds, it can be useful.

2015-11-21 18:21 GMT-02:00 Profpatsch :
On 15-11-19 05:17pm, Cillian de Róiste wrote:
2015-11-19 16:57 GMT+01:00 Profpatsch :
On 15-11-19 02:56am, Roger Qiu wrote:
May I humbly suggest http://stevelosh.com/blog/2013/09/teach-dont-tell/ 
(http://stevelosh.com/blog/2013/09/teach-dont-tell/) as
a general documentation writing template?

I'm a big fan of https://jacobian.org/writing/great-documentation/ 
(https://jacobian.org/writing/great-documentation/)

Yes, that’s what sjl references in the prior reading section as well.
These two are basically the technical writing 101 everyone should know.

--
Proudly written in Mutt with Vim on NixOS.
Q: Why is this email five sentences or less?
A: http://five.sentenc.es (http://five.sentenc.es)
May take up to five days to read your message. If it’s urgent, call me.
___
nix-dev mailing list
nix-dev@lists.science.uu.nl (mailto:nix-dev@lists.science.uu.nl)
http://lists.science.uu.nl/mailman/listinfo/nix-dev 
(http://lists.science.uu.nl/mailman/listinfo/nix-dev)
___
nix-dev mailing list
nix-dev@lists.science.uu.nl (mailto:nix-dev@lists.science.uu.nl)
http://lists.science.uu.nl/mailman/listinfo/nix-dev 
(http://lists.science.uu.nl/mailman/listinfo/nix-dev)
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Profpatsch]

On 15-11-19 05:17pm, Cillian de Róiste wrote:
> 2015-11-19 16:57 GMT+01:00 Profpatsch :
> > On 15-11-19 02:56am, Roger Qiu wrote:
> > May I humbly suggest http://stevelosh.com/blog/2013/09/teach-dont-tell/ as
> > a general documentation writing template?
> 
> I'm a big fan of https://jacobian.org/writing/great-documentation/

Yes, that’s what sjl references in the prior reading section as well.
These two are basically the technical writing 101 everyone should know.

-- 
Proudly written in Mutt with Vim on NixOS.
Q: Why is this email five sentences or less?
A: http://five.sentenc.es
May take up to five days to read your message. If it’s urgent, call me.
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[deCube.net | Danny Wilson]

On 21 nov. 2015, at 01:59, Mathnerd314  wrote:

> On Wed, Nov 18, 2015 at 7:04 AM, Hajo Möller  wrote:
> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.

He said you can’t learn Spanish from just a dictionary.  It may help learn of 
course.


> This is wrong. You can do fine with a dictionary and a few months:
> http://www.theguardian.com/education/2012/nov/09/learn-language-in-three-months
> "When I went online in search of Lingala resources, the only textbook I could 
> find was a US Foreign Service Institute handbook printed in 1963 – when 
> central Africa was still a front of the cold war – and a scanned copy of a 
> 1,109-word Lingala-English dictionary."
> 
> The key here is that he did not have to learn everything at once; he split it 
> up into many small chunks (vocabulary, in his case) that could be focused on 
> independently.
> 
> His most obvious failing once he went to Africa was that he hadn't practiced 
> listening or making complete sentences; some extra hours with a native 
> brought it to an acceptable level.

So... not wrong after all!  A "dictionary alone" was not enough, he had to be 
taught by a native.

https://www.xkcd.com/386/   :-)



> The applicability of said anecdote to NixOS is left as an exercise for the 
> reader.
> 
> -- Mathnerd314
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev




signature.asc
Description: Message signed with OpenPGP using GPGMail
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Vladimír Čunát]

On 11/21/2015 01:59 AM, Mathnerd314 wrote:
> On Wed, Nov 18, 2015 at 7:04 AM, Hajo Möller wrote:
> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.
> 
> This is wrong. You can do fine with a dictionary and a few months [...]

When we're diving into such analogies, I firmly believe that
dictionaries and similarly reference documentation are also very useful,
but they aren't considered optimal as the only resource for beginners
(the focus of Rok's talk).

Vladimir




smime.p7s
Description: S/MIME Cryptographic Signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Mathnerd314]

On Wed, Nov 18, 2015 at 7:04 AM, Hajo Möller  wrote:

> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.
>

This is wrong. You can do fine with a dictionary and a few months:
http://www.theguardian.com/education/2012/nov/09/learn-language-in-three-months
"When I went online in search of Lingala resources, the only textbook I
could find was a US Foreign Service Institute handbook printed in 1963 –
when central Africa  was still a
front of the cold war – and a scanned copy of a 1,109-word Lingala-English
dictionary."

The key here is that he did not have to learn everything at once; he split
it up into many small chunks (vocabulary, in his case) that could be
focused on independently.

His most obvious failing once he went to Africa was that he hadn't
practiced listening or making complete sentences; some extra hours with a
native brought it to an acceptable level.

The applicability of said anecdote to NixOS is left as an exercise for the
reader.

-- Mathnerd314
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Profpatsch]

On 15-11-19 02:56am, Roger Qiu wrote:
> Can the manual be made as a gitbook with the chapters fleshed out better
> and made more user friendly? One  part of the manual can be very fact
> based, another part can be story based. Kind of like the difference between
> documentation vs api documentation vs tutorials. I often find myself across
> 3 to 4 different blog posts, the arch and gentoo wiki, the nixos manual,
> the wiki and github issues because the up to date relevant information is
> everywhere.

May I humbly suggest http://stevelosh.com/blog/2013/09/teach-dont-tell/ as
a general documentation writing template?

-- 
Proudly written in Mutt with Vim on NixOS.
Q: Why is this email five sentences or less?
A: http://five.sentenc.es
May take up to five days to read your message. If it’s urgent, call me.
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Domen Kožar]

You have to think about the audience.

In general following should cover us:

- tutorial (how do I get quickly update to date on X topic)
- user guide (how does a specific feature work)
- reference (functions and what they do)

Currently that's all bundled throughout the manual (and wiki).

Domen

On Wed, Nov 18, 2015 at 5:01 PM, Karsten Gebbert  wrote:

> Hajo Möller  writes:
>
> > As mentioned in another thread, Rok Garbas proposed to remove the wiki
> > and replace it with "real documentation". I fully support this.
> >
> > To follow up on this proposal I suggest we decide what real
> > documentation should look like, so let us reiterate his main points:
> >
> > "Why do we write documentation?"
> > Is it just to remind ourselves about details, or also for helping the
> > readers reach an advanced level of understanding? It should be the both.
> >
> > "There needs to be a clear definition of how documentation is written."
> > We already have coding conventions, but there is no clear how-to for
> > writing good documentation. Maybe (professional) technical writers can
> > chime in here?
> >
> > "Documentation should teach, not tell."
> > As Rok said, handing somebody who is learning a new language a
> > dictionary would not help them learn.
> > It is not possible for us to get an immediate reaction to pinpoint the
> > exact moment our documentation becomes incomprehensible, having our
> > documentation follow a well-defined pattern should help here.
> > This also means we need to hold our users' hands, leading them
> > step-by-step through complex procedures instead of directly presenting
> > results.
> >
> > "You should never tell somebody to read the source."
> > Even though the source code should be self-explanatory (and often is,
> > see the files in nixpkgs/lib for well-commented examples), having real
> > documentation in the form of a manual helps keep everything in the same
> > place. This way there can be a single location where users come to when
> > they are lost.
> >
> > "The manual is good, but not made for beginners."
> > Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> > Although I generally agree, I am not sure where to place those tutorials
> > and what they should cover. Should they be on people's blogs, aggregated
> > in the planet.nixos.org?
> >
> > "Let's kill the wiki, it's not documentation but an abomination."
> > Unmoderated wikis tend to contain outdated or just plain wrong
> > information, it is then arguably better to have no documentation at all
> > than a wiki teaching the wrong things. Also, developers asking (possibly
> > misunderstanding) users to fix the wiki could lead to a scenario where
> > the blind lead the blind.
>
> I think that it would be good to loosely decide on the sections a good
> manual/documentation should consist of. This might help structuring the
> effort
> and break up tasks in meaningful chunks.
>
> I guess the gold standard in FLOSS OS documentation is the Arch Wiki (kind
> of),
> and it would be good to approach the task with its quality and
> comprehensiveness
> as the long-term goal.
>
> From the top of my head, there are multiple aspects to it:
>
> * Cookbook (how do I do XYZ?) e.g.
>   - setting up a Desktop environment
>   - setting up ...
>   - setting up a development environment
>   - detailed guides on developing with in language XYZ
>   - overriding/customizing packages
>   - 
> * nix-* command reference (man pages would probably already suffice)
> * nixpkgs & library (w/ inline docs)
>   - modules
>   - contributors guide
>   - function reference?
> * nix, the language
>   - reference manual
>   - useful snippets?
>
> So, if there is an effort to aggregate information in one place, we could
> split
> up the task according to such a list of sections and work more or less
> independently in branches.
>
> Best,
>
> karsten
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[deCube.net | Danny Wilson]

On 18 nov. 2015, at 16:00, Augustin Borsu  wrote:

> What about having a documentation field in pkgs that allows for markdown?
> Can't get closer to the code than that.


This.
Documentation that’s seperated from code always rots.  Even when you hire 
technical writers...

Related talk from a Technical writer about how Google fixed their docs:  
https://youtu.be/EnB8GtPuauw?t=6m18s

> 
> Also generating an html doc of all the options of a package,
> their default value and maybe a comment by the author of the package
> and an example config would go a lng way.
> 
> Le 18/11/15 15:04, Hajo Möller a écrit :
>> As mentioned in another thread, Rok Garbas proposed to remove the wiki
>> and replace it with "real documentation". I fully support this.
>> 
>> To follow up on this proposal I suggest we decide what real
>> documentation should look like, so let us reiterate his main points:
>> 
>> "Why do we write documentation?"
>> Is it just to remind ourselves about details, or also for helping the
>> readers reach an advanced level of understanding? It should be the both.
>> 
>> "There needs to be a clear definition of how documentation is written."
>> We already have coding conventions, but there is no clear how-to for
>> writing good documentation. Maybe (professional) technical writers can
>> chime in here?
>> 
>> "Documentation should teach, not tell."
>> As Rok said, handing somebody who is learning a new language a
>> dictionary would not help them learn.
>> It is not possible for us to get an immediate reaction to pinpoint the
>> exact moment our documentation becomes incomprehensible, having our
>> documentation follow a well-defined pattern should help here.
>> This also means we need to hold our users' hands, leading them
>> step-by-step through complex procedures instead of directly presenting
>> results.
>> 
>> "You should never tell somebody to read the source."
>> Even though the source code should be self-explanatory (and often is,
>> see the files in nixpkgs/lib for well-commented examples), having real
>> documentation in the form of a manual helps keep everything in the same
>> place. This way there can be a single location where users come to when
>> they are lost.
>> 
>> "The manual is good, but not made for beginners."
>> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
>> Although I generally agree, I am not sure where to place those tutorials
>> and what they should cover. Should they be on people's blogs, aggregated
>> in the planet.nixos.org?
>> 
>> "Let's kill the wiki, it's not documentation but an abomination."
>> Unmoderated wikis tend to contain outdated or just plain wrong
>> information, it is then arguably better to have no documentation at all
>> than a wiki teaching the wrong things. Also, developers asking (possibly
>> misunderstanding) users to fix the wiki could lead to a scenario where
>> the blind lead the blind.
>> 
>> 
> 
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Karsten Gebbert]

Hajo Möller  writes:

> As mentioned in another thread, Rok Garbas proposed to remove the wiki
> and replace it with "real documentation". I fully support this.
>
> To follow up on this proposal I suggest we decide what real
> documentation should look like, so let us reiterate his main points:
>
> "Why do we write documentation?"
> Is it just to remind ourselves about details, or also for helping the
> readers reach an advanced level of understanding? It should be the both.
>
> "There needs to be a clear definition of how documentation is written."
> We already have coding conventions, but there is no clear how-to for
> writing good documentation. Maybe (professional) technical writers can
> chime in here?
>
> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.
> It is not possible for us to get an immediate reaction to pinpoint the
> exact moment our documentation becomes incomprehensible, having our
> documentation follow a well-defined pattern should help here.
> This also means we need to hold our users' hands, leading them
> step-by-step through complex procedures instead of directly presenting
> results.
>
> "You should never tell somebody to read the source."
> Even though the source code should be self-explanatory (and often is,
> see the files in nixpkgs/lib for well-commented examples), having real
> documentation in the form of a manual helps keep everything in the same
> place. This way there can be a single location where users come to when
> they are lost.
>
> "The manual is good, but not made for beginners."
> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> Although I generally agree, I am not sure where to place those tutorials
> and what they should cover. Should they be on people's blogs, aggregated
> in the planet.nixos.org?
>
> "Let's kill the wiki, it's not documentation but an abomination."
> Unmoderated wikis tend to contain outdated or just plain wrong
> information, it is then arguably better to have no documentation at all
> than a wiki teaching the wrong things. Also, developers asking (possibly
> misunderstanding) users to fix the wiki could lead to a scenario where
> the blind lead the blind.

I think that it would be good to loosely decide on the sections a good
manual/documentation should consist of. This might help structuring the effort
and break up tasks in meaningful chunks.

I guess the gold standard in FLOSS OS documentation is the Arch Wiki (kind of),
and it would be good to approach the task with its quality and comprehensiveness
as the long-term goal.

From the top of my head, there are multiple aspects to it:

* Cookbook (how do I do XYZ?) e.g.
  - setting up a Desktop environment
  - setting up ...
  - setting up a development environment
  - detailed guides on developing with in language XYZ
  - overriding/customizing packages
  - 
* nix-* command reference (man pages would probably already suffice)
* nixpkgs & library (w/ inline docs)
  - modules
  - contributors guide
  - function reference? 
* nix, the language
  - reference manual
  - useful snippets?

So, if there is an effort to aggregate information in one place, we could split
up the task according to such a list of sections and work more or less
independently in branches.

Best,

karsten
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Domen Kožar]

I fully agree, and probably others too, but someone has to step up and lead
that effort :)

On Wed, Nov 18, 2015 at 3:04 PM, Hajo Möller  wrote:

> As mentioned in another thread, Rok Garbas proposed to remove the wiki
> and replace it with "real documentation". I fully support this.
>
> To follow up on this proposal I suggest we decide what real
> documentation should look like, so let us reiterate his main points:
>
> "Why do we write documentation?"
> Is it just to remind ourselves about details, or also for helping the
> readers reach an advanced level of understanding? It should be the both.
>
> "There needs to be a clear definition of how documentation is written."
> We already have coding conventions, but there is no clear how-to for
> writing good documentation. Maybe (professional) technical writers can
> chime in here?
>
> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.
> It is not possible for us to get an immediate reaction to pinpoint the
> exact moment our documentation becomes incomprehensible, having our
> documentation follow a well-defined pattern should help here.
> This also means we need to hold our users' hands, leading them
> step-by-step through complex procedures instead of directly presenting
> results.
>
> "You should never tell somebody to read the source."
> Even though the source code should be self-explanatory (and often is,
> see the files in nixpkgs/lib for well-commented examples), having real
> documentation in the form of a manual helps keep everything in the same
> place. This way there can be a single location where users come to when
> they are lost.
>
> "The manual is good, but not made for beginners."
> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> Although I generally agree, I am not sure where to place those tutorials
> and what they should cover. Should they be on people's blogs, aggregated
> in the planet.nixos.org?
>
> "Let's kill the wiki, it's not documentation but an abomination."
> Unmoderated wikis tend to contain outdated or just plain wrong
> information, it is then arguably better to have no documentation at all
> than a wiki teaching the wrong things. Also, developers asking (possibly
> misunderstanding) users to fix the wiki could lead to a scenario where
> the blind lead the blind.
>
>
> --
> Regards,
> Hajo Möller
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Matthias Beyer]

On 18-11-2015 15:40:43, Domen Kožar wrote:
> I fully agree, and probably others too, but someone has to step up and lead
> that effort :)
> 

As said in the other thread, I will try to get something basic working
this weekend, if I have enough time. I'm not sure whether this falls
into "step up and lead that effort".

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Matthias Beyer]

On 18-11-2015 15:04:30, Hajo Möller wrote:
> As mentioned in another thread, Rok Garbas proposed to remove the wiki
> and replace it with "real documentation". I fully support this.

Me too.

> 
> "You should never tell somebody to read the source."
> Even though the source code should be self-explanatory (and often is,
> see the files in nixpkgs/lib for well-commented examples), having real
> documentation in the form of a manual helps keep everything in the same
> place. This way there can be a single location where users come to when
> they are lost.

Keeping everything in one place is a good idea, though we really
should be careful about nix (language), nix (pkg manager) and nixos
mixing. These confused me the first time I dived into the topic.

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

[Nix-dev] Real documentation, aka "Let's kill the wiki"

[Hajo Möller]

As mentioned in another thread, Rok Garbas proposed to remove the wiki
and replace it with "real documentation". I fully support this.

To follow up on this proposal I suggest we decide what real
documentation should look like, so let us reiterate his main points:

"Why do we write documentation?"
Is it just to remind ourselves about details, or also for helping the
readers reach an advanced level of understanding? It should be the both.

"There needs to be a clear definition of how documentation is written."
We already have coding conventions, but there is no clear how-to for
writing good documentation. Maybe (professional) technical writers can
chime in here?

"Documentation should teach, not tell."
As Rok said, handing somebody who is learning a new language a
dictionary would not help them learn.
It is not possible for us to get an immediate reaction to pinpoint the
exact moment our documentation becomes incomprehensible, having our
documentation follow a well-defined pattern should help here.
This also means we need to hold our users' hands, leading them
step-by-step through complex procedures instead of directly presenting
results.

"You should never tell somebody to read the source."
Even though the source code should be self-explanatory (and often is,
see the files in nixpkgs/lib for well-commented examples), having real
documentation in the form of a manual helps keep everything in the same
place. This way there can be a single location where users come to when
they are lost.

"The manual is good, but not made for beginners."
Rok suggests to have tutorials teaching the basics of Nix and NixOS.
Although I generally agree, I am not sure where to place those tutorials
and what they should cover. Should they be on people's blogs, aggregated
in the planet.nixos.org?

"Let's kill the wiki, it's not documentation but an abomination."
Unmoderated wikis tend to contain outdated or just plain wrong
information, it is then arguably better to have no documentation at all
than a wiki teaching the wrong things. Also, developers asking (possibly
misunderstanding) users to fix the wiki could lead to a scenario where
the blind lead the blind.


-- 
Regards,
Hajo Möller

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Augustin Borsu]

What about having a documentation field in pkgs that allows for markdown?
Can't get closer to the code than that.

Also generating an html doc of all the options of a package,
their default value and maybe a comment by the author of the package
and an example config would go a lng way.

Le 18/11/15 15:04, Hajo Möller a écrit :
> As mentioned in another thread, Rok Garbas proposed to remove the wiki
> and replace it with "real documentation". I fully support this.
>
> To follow up on this proposal I suggest we decide what real
> documentation should look like, so let us reiterate his main points:
>
> "Why do we write documentation?"
> Is it just to remind ourselves about details, or also for helping the
> readers reach an advanced level of understanding? It should be the both.
>
> "There needs to be a clear definition of how documentation is written."
> We already have coding conventions, but there is no clear how-to for
> writing good documentation. Maybe (professional) technical writers can
> chime in here?
>
> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.
> It is not possible for us to get an immediate reaction to pinpoint the
> exact moment our documentation becomes incomprehensible, having our
> documentation follow a well-defined pattern should help here.
> This also means we need to hold our users' hands, leading them
> step-by-step through complex procedures instead of directly presenting
> results.
>
> "You should never tell somebody to read the source."
> Even though the source code should be self-explanatory (and often is,
> see the files in nixpkgs/lib for well-commented examples), having real
> documentation in the form of a manual helps keep everything in the same
> place. This way there can be a single location where users come to when
> they are lost.
>
> "The manual is good, but not made for beginners."
> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> Although I generally agree, I am not sure where to place those tutorials
> and what they should cover. Should they be on people's blogs, aggregated
> in the planet.nixos.org?
>
> "Let's kill the wiki, it's not documentation but an abomination."
> Unmoderated wikis tend to contain outdated or just plain wrong
> information, it is then arguably better to have no documentation at all
> than a wiki teaching the wrong things. Also, developers asking (possibly
> misunderstanding) users to fix the wiki could lead to a scenario where
> the blind lead the blind.
>
>

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev