Re: [Nix-dev] Fwd: Wiki is dead
On 02/25/2016 01:39 PM, zimbatm wrote: > The output file wasn't exactly right, I had to replace ` id="something">` to `` tags and wrap it in a tag. That's because pandoc uses an older version of docbook where some tags are different. (IIRC I looked a few months ago and it didn't support the newer one yet.) 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] Fwd: Wiki is dead
On Thu, Feb 25, 2016 at 2:00 PM, Eelco Dolstra wrote: > Hi, > > On 24/02/16 01:14, Anderson Torres wrote: > > > 2016-02-23 19:22 GMT-03:00 zimbatm : > >> I started writing some docbook. Maybe I will get used to it but writing > >> `foobar` is way more > painful > >> that `* foobar` in markdown. Especially in writing I think it's > important to > >> be able to move text around without too much overhead so that text can > be > >> reworked until it feels right. > > I don't think we should let the fact that people are overly attached to > editor > technology from the 1970s be the deciding factor. > > https://help.ubuntu.com/community/DocBookEditors > > >> Thanks god there is pandoc so I can keep submitting docbook while > writing my > >> cozy markdown :) > > > > I think the same. Docbook is extremely verbose and full of ugly XML > > tagging, I don't like it. > > I refer you to my earlier rant about markdown-like languages: > https://github.com/NixOS/nixpkgs/issues/1960#issuecomment-37753960 I never considered that rant as valid, mainly because it's about error handling in markup languages. Compared to our current docbook error handling, where if you put a tag where it should be there is no information what or where it went wrong, markup seems like an improvement. In any case, I'd be up for http://www.sphinx-doc.org/en/stable/ since it has a lot of utilties for documentation we'd need. Anyway, one day I might lack work and this is a first thing on my todo - updating http://static.domenkozar.com/nixpkgs-manual-sphinx-exp/ and making it better :) ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] Fwd: Wiki is dead
Hi, On 24/02/16 01:14, Anderson Torres wrote: > 2016-02-23 19:22 GMT-03:00 zimbatm : >> I started writing some docbook. Maybe I will get used to it but writing >> `foobar` is way more painful >> that `* foobar` in markdown. Especially in writing I think it's important to >> be able to move text around without too much overhead so that text can be >> reworked until it feels right. I don't think we should let the fact that people are overly attached to editor technology from the 1970s be the deciding factor. https://help.ubuntu.com/community/DocBookEditors >> Thanks god there is pandoc so I can keep submitting docbook while writing my >> cozy markdown :) > > I think the same. Docbook is extremely verbose and full of ugly XML > tagging, I don't like it. I refer you to my earlier rant about markdown-like languages: https://github.com/NixOS/nixpkgs/issues/1960#issuecomment-37753960 > But, about documentation: what do you think on a "NixOS Handbook", > like the FreeBSD Handbook? We can reach a wider audience if we use > such a style of handbook. Well, that's what the NixOS Manual is intended for. -- Eelco Dolstra | LogicBlox, Inc. | http://nixos.org/~eelco/ ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] Fwd: Wiki is dead
Basically wrote the doc in markdown and then: ``` $ nix-env -iA nixos.pandoc $ pandoc -f markdown -t docbook release.md > release.xml ``` The output file wasn't exactly right, I had to replace `` to `` tags and wrap it in a tag. That was quickly done and less work that writing in docbook directly. If you don't like markdown it's fine, pandoc is able to translate between a lot of different formats. Input formats: commonmark, docbook, docx, epub, haddock, html, json*, latex, markdown, markdown_github, markdown_mmd, markdown_phpextra, markdown_strict, mediawiki, native, odt, opml, org, rst, t2t, textile, twiki [ *only Pandoc's JSON version of native AST] Output formats: asciidoc, beamer, commonmark, context, docbook, docx, dokuwiki, dzslides, epub, epub3, fb2, haddock, html, html5, icml, json*, latex, man, markdown, markdown_github, markdown_mmd, markdown_phpextra, markdown_strict, mediawiki, native, odt, opendocument, opml, org, pdf**, plain, revealjs, rst, rtf, s5, slideous, slidy, texinfo, textile [**for pdf output, use latex or beamer and -o FILENAME.pdf] On Thu, 25 Feb 2016 at 12:10 Profpatsch wrote: > > On Tue, 23 Feb 2016 at 21:29 Vladimír Čunát wrote: > > > My personal opinion is that this is mostly an excuse. It's a XML subset > > > and everyone should know at least a bit of (X)HTML or similar stuff. > > > Note that for almost all docs we use ~10 types of tags and the format > is > > > by itself human-understandable. (Typically it's enough to copy > fragments > > > from a few paragraphs around and edit to have the new content. We might > > > also compose a list of tags with examples on what we typically use them > > > for.) > > I can confirm that. For small edits, it is enough to copy from the > surroundings. > > On 16-02-23 10:22pm, zimbatm wrote: > > I started writing some docbook. Maybe I will get used to it but writing > > `foobar` is way more > > painful that `* foobar` in markdown. Especially in writing I think it's > > important to be able to move text around without too much overhead so > that > > text can be reworked until it feels right. > > > > Thanks god there is pandoc so I can keep submitting docbook while writing > > my cozy markdown :) > > Maybe we can describe a way to write the docbook documentation in > on the local machine and then convert it to docbook > for check-in. > > What is your setup for that? > > -- > 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] Fwd: Wiki is dead
> On Tue, 23 Feb 2016 at 21:29 Vladimír Čunát wrote: > > My personal opinion is that this is mostly an excuse. It's a XML subset > > and everyone should know at least a bit of (X)HTML or similar stuff. > > Note that for almost all docs we use ~10 types of tags and the format is > > by itself human-understandable. (Typically it's enough to copy fragments > > from a few paragraphs around and edit to have the new content. We might > > also compose a list of tags with examples on what we typically use them > > for.) I can confirm that. For small edits, it is enough to copy from the surroundings. On 16-02-23 10:22pm, zimbatm wrote: > I started writing some docbook. Maybe I will get used to it but writing > `foobar` is way more > painful that `* foobar` in markdown. Especially in writing I think it's > important to be able to move text around without too much overhead so that > text can be reworked until it feels right. > > Thanks god there is pandoc so I can keep submitting docbook while writing > my cozy markdown :) Maybe we can describe a way to write the docbook documentation in on the local machine and then convert it to docbook for check-in. What is your setup for that? -- 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] Fwd: Wiki is dead
Nobody has written the Nix/NixOS book yet. On 24/02/2016 11:14 AM, "Anderson Torres" wrote: > 2016-02-23 19:22 GMT-03:00 zimbatm : > > I started writing some docbook. Maybe I will get used to it but writing > > `foobar` is way more > painful > > that `* foobar` in markdown. Especially in writing I think it's > important to > > be able to move text around without too much overhead so that text can be > > reworked until it feels right. > > > > Thanks god there is pandoc so I can keep submitting docbook while > writing my > > cozy markdown :) > > > > I think the same. Docbook is extremely verbose and full of ugly XML > tagging, I don't like it. > Also, it is easier to use a lightweight markup as pandoc or Asciidoc. > The learning curve is smoother than XML, and it can be easily > converted to Docbook or anything we like. > > But, about documentation: what do you think on a "NixOS Handbook", > like the FreeBSD Handbook? We can reach a wider audience if we use > such a style of handbook. > > > > > On Tue, 23 Feb 2016 at 21:29 Vladimír Čunát wrote: > >> > >> On 02/23/2016 12:18 PM, Rok Garbas wrote: > >> > docbook is just something that is not known by majority of our > community > >> > >> My personal opinion is that this is mostly an excuse. It's a XML subset > >> and everyone should know at least a bit of (X)HTML or similar stuff. > >> Note that for almost all docs we use ~10 types of tags and the format is > >> by itself human-understandable. (Typically it's enough to copy fragments > >> from a few paragraphs around and edit to have the new content. We might > >> also compose a list of tags with examples on what we typically use them > >> for.) > >> > >> In any case, once the HQ content is produced, conversions are easy > >> enough; regardless of doing them at build-time as the trend is now or at > >> commit-time (if we decide later to unify to docbook, for example). > >> > >> --Vladimir > >> > >> > >> ___ > >> 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] Fwd: Wiki is dead
> >I started writing some docbook. Maybe I will get used to it but writing >`foobar` is way more >painful that `* foobar` in markdown. Especially in writing I think it's >important to be able to move text around without too much overhead so that >text can be reworked until it feels right. I also remember that from time to time there is a schema mismatch in the manual (manual is valid XML, but the tag tree is subtly wrong). It can (and sometimes does) require multiple people to understand how to fix that… ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] Fwd: Wiki is dead
2016-02-23 19:22 GMT-03:00 zimbatm : > I started writing some docbook. Maybe I will get used to it but writing > `foobar` is way more painful > that `* foobar` in markdown. Especially in writing I think it's important to > be able to move text around without too much overhead so that text can be > reworked until it feels right. > > Thanks god there is pandoc so I can keep submitting docbook while writing my > cozy markdown :) > I think the same. Docbook is extremely verbose and full of ugly XML tagging, I don't like it. Also, it is easier to use a lightweight markup as pandoc or Asciidoc. The learning curve is smoother than XML, and it can be easily converted to Docbook or anything we like. But, about documentation: what do you think on a "NixOS Handbook", like the FreeBSD Handbook? We can reach a wider audience if we use such a style of handbook. > > On Tue, 23 Feb 2016 at 21:29 Vladimír Čunát wrote: >> >> On 02/23/2016 12:18 PM, Rok Garbas wrote: >> > docbook is just something that is not known by majority of our community >> >> My personal opinion is that this is mostly an excuse. It's a XML subset >> and everyone should know at least a bit of (X)HTML or similar stuff. >> Note that for almost all docs we use ~10 types of tags and the format is >> by itself human-understandable. (Typically it's enough to copy fragments >> from a few paragraphs around and edit to have the new content. We might >> also compose a list of tags with examples on what we typically use them >> for.) >> >> In any case, once the HQ content is produced, conversions are easy >> enough; regardless of doing them at build-time as the trend is now or at >> commit-time (if we decide later to unify to docbook, for example). >> >> --Vladimir >> >> >> ___ >> 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] Fwd: Wiki is dead
I started writing some docbook. Maybe I will get used to it but writing `foobar` is way more painful that `* foobar` in markdown. Especially in writing I think it's important to be able to move text around without too much overhead so that text can be reworked until it feels right. Thanks god there is pandoc so I can keep submitting docbook while writing my cozy markdown :) On Tue, 23 Feb 2016 at 21:29 Vladimír Čunát wrote: > On 02/23/2016 12:18 PM, Rok Garbas wrote: > > docbook is just something that is not known by majority of our community > > My personal opinion is that this is mostly an excuse. It's a XML subset > and everyone should know at least a bit of (X)HTML or similar stuff. > Note that for almost all docs we use ~10 types of tags and the format is > by itself human-understandable. (Typically it's enough to copy fragments > from a few paragraphs around and edit to have the new content. We might > also compose a list of tags with examples on what we typically use them > for.) > > In any case, once the HQ content is produced, conversions are easy > enough; regardless of doing them at build-time as the trend is now or at > commit-time (if we decide later to unify to docbook, for example). > > --Vladimir > > > ___ > 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] Fwd: Wiki is dead
On 02/23/2016 12:18 PM, Rok Garbas wrote: > docbook is just something that is not known by majority of our community My personal opinion is that this is mostly an excuse. It's a XML subset and everyone should know at least a bit of (X)HTML or similar stuff. Note that for almost all docs we use ~10 types of tags and the format is by itself human-understandable. (Typically it's enough to copy fragments from a few paragraphs around and edit to have the new content. We might also compose a list of tags with examples on what we typically use them for.) In any case, once the HQ content is produced, conversions are easy enough; regardless of doing them at build-time as the trend is now or at commit-time (if we decide later to unify to docbook, for example). --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] Fwd: Wiki is dead
On 16-02-20 03:11pm, Anthony Cowley wrote: > The point being that once a wiki item gets a handful of positive votes, it > gets turned into an Issue on the manual for someone with a better > understanding of how things are put together to find it a home. At that > point, the wiki item could have a link to the manual added. fyi, that’s exactly how it happened with the Haskell Documentation. It was first put in the wiki and once it became more “official” extended and put into the manual. -- 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] Fwd: Wiki is dead
Hi Eelco, >> I've given this a try [1] for the zero-build-failures entry and my >> experience so >> far was: >> >> 1/ How do I actually build docbook? >> => copy doc/default.nix and adjust >> 2/ nix-build is rebuilding GHC 7.8 and 7.10 (for pandoc I think). >> => Wait 2h. >> 3/ GHC build fails [2] >> 4/ We're not using standard docbook but preprocess with XSLT so references on >> the internet don't actually work. > > This speaks in favor of keeping *all* docs in Docbook format so we don't need > conversion tools like Pandoc. Then the manual generation only depends on > xsltproc and docbook-xsl. This is pretty much a hard requirement for the > NixOS > manual because I don't think it's a good idea for the core system to pull in > Pandoc. > > In fact, I think having multiple formats is not a good idea in general, > because > it makes it hard to restructure the manual (e.g., you can't just move a manual > fragment between different sections if they're written in different formats). > And it requires contributors to learn the idiosyncrasies of multiple formats. > adding another tool to the build chain is something nobody wants. we all agree on that. on the other hand we _must_ look at why contributors are using other tools. docbook is just something that is not known by majority of our community. markdown or such would be much more generally accepted markup, which wouldn't require majority of our community to learn in order to contribute to documentation. current situation is as it is and while we migrate wiki and refactor the manual into something also more suitable for newcomers, we should not change the tools. but as we will move forward with the project i urge you to consider some other markup for documentation which have bigger community adoption. i will learn whatever is decided (even docbook), but i will be very hard to convince others to do as well. i would not like to rush in any decision, but please put some thoughts on this. once you said "until i'm mostly the only one writing documentation we will not change from docbook". i hope that in next months i will be able to show you that documentation is being written/extended by many and many more would contribute if docbook wouldn't be an obstacle. my only goal is to have as good documentation as possible. i'm sure everybody feels the same. i think we can also agree that the only way to keep documentation of a community project like this is that everybody contributes. being docbook or any other markup please consider giving a hand. thank you! -- Rok Garbas - https://www.garbas.si ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] Fwd: Wiki is dead
Hi, On 22/02/16 00:58, Thomas Hunger wrote: > I've given this a try [1] for the zero-build-failures entry and my experience > so > far was: > > 1/ How do I actually build docbook? > => copy doc/default.nix and adjust > 2/ nix-build is rebuilding GHC 7.8 and 7.10 (for pandoc I think). > => Wait 2h. > 3/ GHC build fails [2] > 4/ We're not using standard docbook but preprocess with XSLT so references on > the internet don't actually work. This speaks in favor of keeping *all* docs in Docbook format so we don't need conversion tools like Pandoc. Then the manual generation only depends on xsltproc and docbook-xsl. This is pretty much a hard requirement for the NixOS manual because I don't think it's a good idea for the core system to pull in Pandoc. In fact, I think having multiple formats is not a good idea in general, because it makes it hard to restructure the manual (e.g., you can't just move a manual fragment between different sections if they're written in different formats). And it requires contributors to learn the idiosyncrasies of multiple formats. -- Eelco Dolstra | LogicBlox, Inc. | http://nixos.org/~eelco/ ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] Fwd: Wiki is dead
On 02/22/2016 12:58 AM, Thomas Hunger wrote: > 2/ nix-build is rebuilding GHC 7.8 and 7.10 (for pandoc I think). Basing your work on a channel should remove such problems, as for any regular package. --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] Fwd: Wiki is dead
Thanks Rok! I've given this a try [1] for the zero-build-failures entry and my experience so far was: 1/ How do I actually build docbook? => copy doc/default.nix and adjust 2/ nix-build is rebuilding GHC 7.8 and 7.10 (for pandoc I think). => Wait 2h. 3/ GHC build fails [2] 4/ We're not using standard docbook but preprocess with XSLT so references on the internet don't actually work. While I think the docbook format itself is fine for describing the content the process isn't. IMO it must be reasonably simple to contribute or fix an entry. Would you be opposed to a directory full of markdown files for now? Those can be pandoc-ed into almost anything later without too much formatting loss IIUC? ~ [1] https://github.com/teh/nixpkgs/commit/a29e27820f3ea1d101c544241a80354237b39b89 [2] /nix/store/9vp1v2s43s92z05jm0ywnqxiq16rh5q9-ghc-7.10.3/lib/ghc-7.10.3/bin/ghc-pkg: error while loading shared libraries: libHSterminfo-0.4.0.1-6iVf4EBnOgfIaaOCLRs8jl-ghc7.10.3.so: cannot open shared object file: No such file or directory On 21 February 2016 at 21:27, Rok Garbas wrote: > Hi all, > > As some already seen I create tickets for each page in wiki (more or > less) each wiki page. > All are assigned to "Move the wiki!"[1] milestone, so we can track the > progress. > > Because of the quantity of content that needs to be migrated, and most > importantly reviewed, we must move with small steps since one-evening > migration away from current wiki is not possible. > > Next step is triaging and getting everybody involved to produce best > documentation we can. I'm hoping that migration of the wiki will be > done in a month (or sooner). Current status is we have 180 open > tickets, I will keep the mailing list updated on the status of the > migration on bi-weekly basis. > > Few things that some already asked me: > - we are not moving away from docbook format at this stage (we need > to fix one thing at the time) > - contributions via PR's is just another form of a wiki, which fits > into our current workflow and removes > - there will be more documents then just manual (tutorial, cookbooks, > getting started, ...) but conversation about this started some in > another tread so lets continue conversation there. > > Important to know is that nothing will happen over night, but we must > keep improving our documentation. I have no doubt that in one year it > will be much easier to learn/use/play with Nix/NixOS. > > > [1] https://github.com/NixOS/nixpkgs/milestones/Move%20the%20wiki! > > -- > Rok Garbas - https://garbas.si > ___ > 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] Fwd: Wiki is dead
Hi all, As some already seen I create tickets for each page in wiki (more or less) each wiki page. All are assigned to "Move the wiki!"[1] milestone, so we can track the progress. Because of the quantity of content that needs to be migrated, and most importantly reviewed, we must move with small steps since one-evening migration away from current wiki is not possible. Next step is triaging and getting everybody involved to produce best documentation we can. I'm hoping that migration of the wiki will be done in a month (or sooner). Current status is we have 180 open tickets, I will keep the mailing list updated on the status of the migration on bi-weekly basis. Few things that some already asked me: - we are not moving away from docbook format at this stage (we need to fix one thing at the time) - contributions via PR's is just another form of a wiki, which fits into our current workflow and removes - there will be more documents then just manual (tutorial, cookbooks, getting started, ...) but conversation about this started some in another tread so lets continue conversation there. Important to know is that nothing will happen over night, but we must keep improving our documentation. I have no doubt that in one year it will be much easier to learn/use/play with Nix/NixOS. [1] https://github.com/NixOS/nixpkgs/milestones/Move%20the%20wiki! -- Rok Garbas - https://garbas.si ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] Fwd: Wiki is dead
> On Feb 20, 2016, at 3:20 PM, Kosyrev Serge <_deepf...@feelingofgreen.ru> > wrote: > > Anthony Cowley writes: >> Bringing together what Thomas and Freddy say here, it seems to me that >> a rather ideal mixture would be something unstructured like a wiki >> with buttons for readers saying, "This helped me" or "This did not >> work". >> >> The point being that once a wiki item gets a handful of positive >> votes, it gets turned into an Issue on the manual for someone with a >> better understanding of how things are put together to find it a home. > > Anthony, this is an excellent idea that you have came up to! > > The question that immediately comes my mind is -- what "this" would mean? > > A section? A paragraph? Something even more structured? > > ..and then there is this perpetually simple matter of programming > to make it happen.. > > -- > с уважениeм / respectfully, > Косырев Сергей I was imagining feedback attached to section headings. They could perhaps be buttons inserted with CSS/JS or something tied more into the wiki engine. The links could ping a counter running as a separate web service with what page/section they are associated with. I think the feedback mechanism should be as simple as a Reddit upvote since any impact it has will be mediated by an expert reviewer who will use their judgment to determine what valuable nuggets should be promoted to the manual. Anthony ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] Fwd: Wiki is dead
Bringing together what Thomas and Freddy say here, it seems to me that a rather ideal mixture would be something unstructured like a wiki with buttons for readers saying, "This helped me" or "This did not work". The point being that once a wiki item gets a handful of positive votes, it gets turned into an Issue on the manual for someone with a better understanding of how things are put together to find it a home. At that point, the wiki item could have a link to the manual added. Similarly, things marked obsolete could at some point get a review from an expert who could make the obsolescence official so that the item gets a big red banner warning future readers. The expert reviewer could zero out the counts if the votes are due to misunderstandings. The votes are not for publicity, but for triage. This does not address spam, but offloading authentication to someone like github could still be used. What this does is free would-be doc or recipe contributors from being paralyzed by unfamiliarity with language style or naming conventions, while still establishing a path for their contributions to make it into the manual. Anthony > On Feb 20, 2016, at 8:54 AM, Freddy Rietdijk wrote: > > Adding documentation is one thing, maintaining it is a second. It's great if > someone is willing to convert contributions to Docbook, and I'm thankful for > that. However, that does not help much if you want to modify parts of it. And > as Nixpkgs is updated, so should the documentation. > > I agree writing docs isn't peoples favorite activity, but somehow, when I see > the amount of content that's on the Wiki, I do wonder: how come people chose > to put it there instead of in the manual? Was it because there never really > was a manual where the contents would fit in? Or was it because it was more > convenient to contribute to the wiki instead of the manual? > I haven't been around long enough with this project, so I don't know. Some of > you will have a better idea. > > Being able to convert to Docbook like is done with the Haskell guide makes it > easier for others to contribute, at least, if you know how that conversion is > done. > > Some time ago I began using Nix because I like it. Python packaging is a mess > as Domen explained during NixCon, but with Nix it works much better. I've > contributed Python packages, and now I would like to share how it is done. As > acoustician/researcher my work activities are quite different from I bet most > other Nix users. Learning Nix was a big investment, but is I think worth it. > Learning Docbook on the other hand... > > If you want to scare away contributors by keeping the barrier high, then keep > the documentation the way it is. > > > >> On Sat, Feb 20, 2016 at 2:04 PM, Thomas Hunger wrote: >> I'm tool agnostic but +1 on having a cookbook in git for the review-workflow >> (avoids wiki spam). I have a number of snippets (how to remove gc roots, >> haskell profiling, how to use ihaskell properly, many more) but no good >> place to put them. >> >> I've started a git-book thing [1] a while back to collect these but didn't >> get very far. I'd much rather contribute to a common, low-barrier-to-entry >> repository than rolling my own. >> >> In my experience just providing the structure will eventually attract >> content because adding a small snippet is the path of least resistance for >> each individual contributor. Maybe we could add a banner "This is how you >> add a snippet" and buttons "File a bug that this is wrong / outdated" to >> each snippet? >> >> Rok - I know it's not free software but maybe it's worth setting up a google >> docs spreadsheet for coordinating the migration once we've settled on a >> tool? I will contribute. >> >> ~ >> >> [1] >> https://github.com/WeAreWizards/nixbyexample >> >>> On 20 February 2016 at 12:06, Freddy Rietdijk >>> wrote: >>> I agree with Vladimir that we already have the infrastructure, the Nixpkgs >>> repository. >>> >>> What is needed is a clearer way where to put certain documentation and a >>> lower barrier for contributing. In `Redesign of documentation` I came with >>> a proposal of how to structure the documentation. A wiki has a low barrier >>> for contributing, however, it also has many disadvantages, which you would >>> not have if we use, say, the Nixpkgs repository. >>> >>> A big barrier, in my opinion and I'm pretty sure also in that of others, is >>> the current format of the Nixpkgs manual. I can understand why docbook is >>> used, and I think it should be used for say the Nix manual, but for a >>> User's Guide to which many of us would/should contribute, the barrier is >>> just too high. >>> >>> On the branch https://github.com/FRidh/nixpkgs/tree/usersguide I >>> implemented the proposed redesign. >>> The documentation is split into two documents, the User's Guide, and the >>> Contributor's Guide. The User's Guide is divided into three parts: >>> Intro
Re: [Nix-dev] Fwd: Wiki is dead
On Saturday, February 20, 2016 15:16:12 zimbatm wrote: > That's exactly why the wiki is good. The contribution barrier is fairly low > and you can do things without having to ask for permission. > It's very easy for anyone to come along and fix typos. Having the change > appear directly is also much more rewarding than having to file a PR and > then potentially have people bikeshed about what you did. Edit, change, > submit. Done. The way I see it is that everyone understands that lowering the barrier of entry will encourage contributions. The problem is that people have exactly the opposite opinions as to what the barrier is :) For example, for me, the barrier for contributing to the manual is that the contribution has to be structured, must be up to standards etc etc. So, instead of writing down a simple how-to note, I would need to do a lot more work so it's tagged "will do later"(read "never":)) The web interface is also a much bigger hassle to use than dropping an *.md file into a git repo. I don't even have to commit it right away. The practical and psychological barrier is the lowest in this case, but only if I have the commit rights otherwise I'd probably resort to submitting batches of notes in one PR. ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] Fwd: Wiki is dead
That's exactly why the wiki is good. The contribution barrier is fairly low and you can do things without having to ask for permission. It's very easy for anyone to come along and fix typos. Having the change appear directly is also much more rewarding than having to file a PR and then potentially have people bikeshed about what you did. Edit, change, submit. Done. For me the wiki is a good staging area where people can collect information. The content is not necessarily very well structured and can be outdated. Once we have good chunks of documentation we can always port them to the manuals or guides (which are also good to have but are a different subject). The only thing is that since anyone can make changes, we need a couple of maintainers that keep a friendly but watchful eye on the wiki and adjust as needed. Instead of checking things upfront we would be checking things after they are happening. For this we subscribe to the change feed. On Sat, 20 Feb 2016 at 13:54 Freddy Rietdijk wrote: > Adding documentation is one thing, maintaining it is a second. It's great > if someone is willing to convert contributions to Docbook, and I'm thankful > for that. However, that does not help much if you want to modify parts of > it. And as Nixpkgs is updated, so should the documentation. > > I agree writing docs isn't peoples favorite activity, but somehow, when I > see the amount of content that's on the Wiki, I do wonder: how come people > chose to put it there instead of in the manual? Was it because there never > really was a manual where the contents would fit in? Or was it because it > was more convenient to contribute to the wiki instead of the manual? > I haven't been around long enough with this project, so I don't know. Some > of you will have a better idea. > > Being able to convert to Docbook like is done with the Haskell guide makes > it easier for others to contribute, at least, if you know how that > conversion is done. > > Some time ago I began using Nix because I like it. Python packaging is a > mess as Domen explained during NixCon, but with Nix it works much better. > I've contributed Python packages, and now I would like to share how it is > done. As acoustician/researcher my work activities are quite different from > I bet most other Nix users. Learning Nix was a big investment, but is I > think worth it. Learning Docbook on the other hand... > > If you want to scare away contributors by keeping the barrier high, then > keep the documentation the way it is. > > > > On Sat, Feb 20, 2016 at 2:04 PM, Thomas Hunger wrote: > >> I'm tool agnostic but +1 on having a cookbook in git for the >> review-workflow (avoids wiki spam). I have a number of snippets (how to >> remove gc roots, haskell profiling, how to use ihaskell properly, many >> more) but no good place to put them. >> >> I've started a git-book thing [1] a while back to collect these but >> didn't get very far. I'd much rather contribute to a common, >> low-barrier-to-entry repository than rolling my own. >> >> In my experience just providing the structure will eventually attract >> content because adding a small snippet is the path of least resistance for >> each individual contributor. Maybe we could add a banner "This is how you >> add a snippet" and buttons "File a bug that this is wrong / outdated" to >> each snippet? >> >> Rok - I know it's not free software but maybe it's worth setting up a >> google docs spreadsheet for coordinating the migration once we've settled >> on a tool? I will contribute. >> >> ~ >> >> [1] >> https://github.com/WeAreWizards/nixbyexample >> >> On 20 February 2016 at 12:06, Freddy Rietdijk >> wrote: >> >>> I agree with Vladimir that we already have the infrastructure, the >>> Nixpkgs repository. >>> >>> What is needed is a clearer way where to put certain documentation and a >>> lower barrier for contributing. In `Redesign of documentation` I came with >>> a proposal of how to structure the documentation. A wiki has a low barrier >>> for contributing, however, it also has many disadvantages, which you would >>> not have if we use, say, the Nixpkgs repository. >>> >>> A big barrier, in my opinion and I'm pretty sure also in that of others, >>> is the current format of the Nixpkgs manual. I can understand why docbook >>> is used, and I think it should be used for say the Nix manual, but for a >>> User's Guide to which many of us would/should contribute, the barrier is >>> just too high. >>> >>> On the branch https://github.com/FRidh/nixpkgs/tree/usersguide I >>> implemented the proposed redesign. >>> The documentation is split into two documents, the User's Guide, and the >>> Contributor's Guide. The User's Guide is divided into three parts: >>> >>>- Introduction >>>- Reference >>>- Cookbook >>> >>> There have been several proposals already for tools/implementations >>> (Matthias' Jekyll implementation, Domens Sphinx docs) . Here I chose to go >>> also for the Sphinx documentation generator.
Re: [Nix-dev] Fwd: Wiki is dead
Adding documentation is one thing, maintaining it is a second. It's great if someone is willing to convert contributions to Docbook, and I'm thankful for that. However, that does not help much if you want to modify parts of it. And as Nixpkgs is updated, so should the documentation. I agree writing docs isn't peoples favorite activity, but somehow, when I see the amount of content that's on the Wiki, I do wonder: how come people chose to put it there instead of in the manual? Was it because there never really was a manual where the contents would fit in? Or was it because it was more convenient to contribute to the wiki instead of the manual? I haven't been around long enough with this project, so I don't know. Some of you will have a better idea. Being able to convert to Docbook like is done with the Haskell guide makes it easier for others to contribute, at least, if you know how that conversion is done. Some time ago I began using Nix because I like it. Python packaging is a mess as Domen explained during NixCon, but with Nix it works much better. I've contributed Python packages, and now I would like to share how it is done. As acoustician/researcher my work activities are quite different from I bet most other Nix users. Learning Nix was a big investment, but is I think worth it. Learning Docbook on the other hand... If you want to scare away contributors by keeping the barrier high, then keep the documentation the way it is. On Sat, Feb 20, 2016 at 2:04 PM, Thomas Hunger wrote: > I'm tool agnostic but +1 on having a cookbook in git for the > review-workflow (avoids wiki spam). I have a number of snippets (how to > remove gc roots, haskell profiling, how to use ihaskell properly, many > more) but no good place to put them. > > I've started a git-book thing [1] a while back to collect these but didn't > get very far. I'd much rather contribute to a common, low-barrier-to-entry > repository than rolling my own. > > In my experience just providing the structure will eventually attract > content because adding a small snippet is the path of least resistance for > each individual contributor. Maybe we could add a banner "This is how you > add a snippet" and buttons "File a bug that this is wrong / outdated" to > each snippet? > > Rok - I know it's not free software but maybe it's worth setting up a > google docs spreadsheet for coordinating the migration once we've settled > on a tool? I will contribute. > > ~ > > [1] > https://github.com/WeAreWizards/nixbyexample > > On 20 February 2016 at 12:06, Freddy Rietdijk > wrote: > >> I agree with Vladimir that we already have the infrastructure, the >> Nixpkgs repository. >> >> What is needed is a clearer way where to put certain documentation and a >> lower barrier for contributing. In `Redesign of documentation` I came with >> a proposal of how to structure the documentation. A wiki has a low barrier >> for contributing, however, it also has many disadvantages, which you would >> not have if we use, say, the Nixpkgs repository. >> >> A big barrier, in my opinion and I'm pretty sure also in that of others, >> is the current format of the Nixpkgs manual. I can understand why docbook >> is used, and I think it should be used for say the Nix manual, but for a >> User's Guide to which many of us would/should contribute, the barrier is >> just too high. >> >> On the branch https://github.com/FRidh/nixpkgs/tree/usersguide I >> implemented the proposed redesign. >> The documentation is split into two documents, the User's Guide, and the >> Contributor's Guide. The User's Guide is divided into three parts: >> >>- Introduction >>- Reference >>- Cookbook >> >> There have been several proposals already for tools/implementations >> (Matthias' Jekyll implementation, Domens Sphinx docs) . Here I chose to go >> also for the Sphinx documentation generator. It allows you to write >> RestructuredText. With a small plugin, which I enabled, you can also >> include CommonMark/Markdown. Nix highlighting is supported. >> The result can be found at http://nixpkgs.readthedocs.org/en/latest/ . >> It's mostly empty still. >> >> Now this is only a proposal, and I'm open to other ways. But I really >> think we should do something about the current state of the docs, in both >> content and lowering the barrier. ReStructuredText/Markdown obviously >> doesn't have as much possibilities as Docbook but what matters eventually >> is whether it is enough, and I think it will be, at least for now. >> >> >> On Sat, Feb 20, 2016 at 12:30 PM, Vladimír Čunát >> wrote: >> >>> On 02/20/2016 12:52 AM, zimbatm wrote: >>> > It's a great staging area for content where people can edit without >>> > asking for permission. [...] >>> >>> What are the advantages in comparison to standard pull requests with >>> discussion underneath? We already have lots of infrastructure advantages >>> in there, such as merging changes at once with documentation for them, >>> auto-mention bot, etc. >>> >>> >
Re: [Nix-dev] Fwd: Wiki is dead
I'm tool agnostic but +1 on having a cookbook in git for the review-workflow (avoids wiki spam). I have a number of snippets (how to remove gc roots, haskell profiling, how to use ihaskell properly, many more) but no good place to put them. I've started a git-book thing [1] a while back to collect these but didn't get very far. I'd much rather contribute to a common, low-barrier-to-entry repository than rolling my own. In my experience just providing the structure will eventually attract content because adding a small snippet is the path of least resistance for each individual contributor. Maybe we could add a banner "This is how you add a snippet" and buttons "File a bug that this is wrong / outdated" to each snippet? Rok - I know it's not free software but maybe it's worth setting up a google docs spreadsheet for coordinating the migration once we've settled on a tool? I will contribute. ~ [1] https://github.com/WeAreWizards/nixbyexample On 20 February 2016 at 12:06, Freddy Rietdijk wrote: > I agree with Vladimir that we already have the infrastructure, the Nixpkgs > repository. > > What is needed is a clearer way where to put certain documentation and a > lower barrier for contributing. In `Redesign of documentation` I came with > a proposal of how to structure the documentation. A wiki has a low barrier > for contributing, however, it also has many disadvantages, which you would > not have if we use, say, the Nixpkgs repository. > > A big barrier, in my opinion and I'm pretty sure also in that of others, > is the current format of the Nixpkgs manual. I can understand why docbook > is used, and I think it should be used for say the Nix manual, but for a > User's Guide to which many of us would/should contribute, the barrier is > just too high. > > On the branch https://github.com/FRidh/nixpkgs/tree/usersguide I > implemented the proposed redesign. > The documentation is split into two documents, the User's Guide, and the > Contributor's Guide. The User's Guide is divided into three parts: > >- Introduction >- Reference >- Cookbook > > There have been several proposals already for tools/implementations > (Matthias' Jekyll implementation, Domens Sphinx docs) . Here I chose to go > also for the Sphinx documentation generator. It allows you to write > RestructuredText. With a small plugin, which I enabled, you can also > include CommonMark/Markdown. Nix highlighting is supported. > The result can be found at http://nixpkgs.readthedocs.org/en/latest/ . > It's mostly empty still. > > Now this is only a proposal, and I'm open to other ways. But I really > think we should do something about the current state of the docs, in both > content and lowering the barrier. ReStructuredText/Markdown obviously > doesn't have as much possibilities as Docbook but what matters eventually > is whether it is enough, and I think it will be, at least for now. > > > On Sat, Feb 20, 2016 at 12:30 PM, Vladimír Čunát wrote: > >> On 02/20/2016 12:52 AM, zimbatm wrote: >> > It's a great staging area for content where people can edit without >> > asking for permission. [...] >> >> What are the advantages in comparison to standard pull requests with >> discussion underneath? We already have lots of infrastructure advantages >> in there, such as merging changes at once with documentation for them, >> auto-mention bot, etc. >> >> >> >> ___ >> 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] Fwd: Wiki is dead
Someone (I think Vladimir?) offered to translate docs in any format into the necessary docbook, and has done so at least for one of my PRs. As long as that offer still stands and isn't overwhelming him, we can avoid spending time and resources switching over our format until we actually have evidence that people will write docs in the new format. I suspect format is a red herring here. People don't like writing docs. ~Shea On 2016-02-20 07:06, Freddy Rietdijk wrote: > I agree with Vladimir that we already have the infrastructure, the > Nixpkgs repository. > > What is needed is a clearer way where to put certain documentation > and a lower barrier for contributing. In `Redesign of documentation` > I > came with a proposal of how to structure the documentation. A wiki > has > a low barrier for contributing, however, it also has many > disadvantages, which you would not have if we use, say, the Nixpkgs > repository. > > A big barrier, in my opinion and I'm pretty sure also in that of > others, is the current format of the Nixpkgs manual. I can understand > why docbook is used, and I think it should be used for say the Nix > manual, but for a User's Guide to which many of us would/should > contribute, the barrier is just too high. > > On the branch https://github.com/FRidh/nixpkgs/tree/usersguide [2] I > implemented the proposed redesign. > The documentation is split into two documents, the User's Guide, and > the Contributor's Guide. The User's Guide is divided into three > parts: > > * Introduction > > * Reference > > * Cookbook > > There have been several proposals already for tools/implementations > (Matthias' Jekyll implementation, Domens Sphinx docs) . Here I chose > to go also for the Sphinx documentation generator. It allows you to > write RestructuredText. With a small plugin, which I enabled, you can > also include CommonMark/Markdown. Nix highlighting is supported. > > The result can be found at http://nixpkgs.readthedocs.org/en/latest/ > [3] . It's mostly empty still. > > Now this is only a proposal, and I'm open to other ways. But I really > think we should do something about the current state of the docs, in > both content and lowering the barrier. ReStructuredText/Markdown > obviously doesn't have as much possibilities as Docbook but what > matters eventually is whether it is enough, and I think it will be, > at > least for now. > > On Sat, Feb 20, 2016 at 12:30 PM, Vladimír Čunát > wrote: > >> On 02/20/2016 12:52 AM, zimbatm wrote: >> > It's a great staging area for content where people can edit >> without >> > asking for permission. [...] >> >> What are the advantages in comparison to standard pull requests with >> discussion underneath? We already have lots of infrastructure >> advantages >> in there, such as merging changes at once with documentation for >> them, >> auto-mention bot, etc. >> >> ___ >> nix-dev mailing list >> nix-dev@lists.science.uu.nl >> http://lists.science.uu.nl/mailman/listinfo/nix-dev [1] > > > > Links: > -- > [1] http://lists.science.uu.nl/mailman/listinfo/nix-dev > [2] https://github.com/FRidh/nixpkgs/tree/usersguide > [3] http://nixpkgs.readthedocs.org/en/latest/ > > ___ > 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] Fwd: Wiki is dead
I agree with Vladimir that we already have the infrastructure, the Nixpkgs repository. What is needed is a clearer way where to put certain documentation and a lower barrier for contributing. In `Redesign of documentation` I came with a proposal of how to structure the documentation. A wiki has a low barrier for contributing, however, it also has many disadvantages, which you would not have if we use, say, the Nixpkgs repository. A big barrier, in my opinion and I'm pretty sure also in that of others, is the current format of the Nixpkgs manual. I can understand why docbook is used, and I think it should be used for say the Nix manual, but for a User's Guide to which many of us would/should contribute, the barrier is just too high. On the branch https://github.com/FRidh/nixpkgs/tree/usersguide I implemented the proposed redesign. The documentation is split into two documents, the User's Guide, and the Contributor's Guide. The User's Guide is divided into three parts: - Introduction - Reference - Cookbook There have been several proposals already for tools/implementations (Matthias' Jekyll implementation, Domens Sphinx docs) . Here I chose to go also for the Sphinx documentation generator. It allows you to write RestructuredText. With a small plugin, which I enabled, you can also include CommonMark/Markdown. Nix highlighting is supported. The result can be found at http://nixpkgs.readthedocs.org/en/latest/ . It's mostly empty still. Now this is only a proposal, and I'm open to other ways. But I really think we should do something about the current state of the docs, in both content and lowering the barrier. ReStructuredText/Markdown obviously doesn't have as much possibilities as Docbook but what matters eventually is whether it is enough, and I think it will be, at least for now. On Sat, Feb 20, 2016 at 12:30 PM, Vladimír Čunát wrote: > On 02/20/2016 12:52 AM, zimbatm wrote: > > It's a great staging area for content where people can edit without > > asking for permission. [...] > > What are the advantages in comparison to standard pull requests with > discussion underneath? We already have lots of infrastructure advantages > in there, such as merging changes at once with documentation for them, > auto-mention bot, etc. > > > > ___ > 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