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

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

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

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,

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

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

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

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

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

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

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

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

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

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:

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

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 >

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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:

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

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

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

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

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

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...

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

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

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

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

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

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

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

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

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

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?"

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

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