[Nix-dev] Yet Another idea About the Wiki

[Benno Fünfstück]

Hi,

I don't see how this proposal is better than just placing the documentation
in some markup format in the nixpkgs repository itself.  Compared to your
proposed approach, that would have at least two advantages:

* documentation is at least near to the code, making it easier to sync it
with changes.
* even non - core devs can edit the documentation, but their contributions
have to be reviewed by a core dev.

Regards,
Benno

Martin Vahi <martin.vahi at softf1.com> schrieb am Do., 19. Nov. 2015 03:58:

> I'm one of those people, who is new to Nix and
> is trying to learn it. What regards to the idea
> of killing the wiki, then I suggest that You
> just make a wiki that is editable only to
> the people, who have been with the project for
> a long time and know, what they are writing about.
>
> Once upon a time, years ago, at one of my jobs
> we solved the problem so that we had an internal
> wiki that only the core developers could edit
> and then the rest, PDF/static-HTML/whatever that went
> to the end users, was automatically generated
> from that wiki by the release team. The generated
> documentation was bundled with the application,
> like at the old times on Windows, where each
> application had a Help menu with documentation, except
> that in stead of the Windows CHM-files the application
> launched the default web browser with a local file
> URL to the static, bundled, HTML.
>
> It worked fine. Everyone were happy, even the
> ones that wanted to print PDF-s.
>
> There were 2 types of documentation: the "tutorial"
> and the API doc. In the case of the API doc we used
> special syntax that was used by the application
> for showing the documentation dynamically, at its
> proprietary IDE.
>
> We actually made quite many iterations before
> coming up with the wiki based solution and the
> end result worked like a charm. :-D
>
> Of course, the difficulty is the modification of the
> wiki software, but, life is tough, so that just has
> to be lived with.
>
> With a hope of being useful,
> Martin.Vahi at softf1.com
>
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20151119/c4b39a2d/attachment.html