[Nix-dev] Restructuring of the Wiki

Mon May 19 10:03:47 CEST 2014

Small note first:
s/Markdown/Pandoc<http://www.johnmacfarlane.net/pandoc/README.html>Markdown/
(and this `s/.../.../` thing has to do with `sed`, in case you
wonder). I guess many of the NixOS people live in the Haskell world, and
`pandoc` is the tool of choice there. The good news is that it supports
_both_ reading and writing MediaWiki markup, so it is possible to write
markdown, convert to MediaWiki markup and upload it into MediaWiki's
database, edit it in MediaWiki and then convert back to markdown.

And this brings us to the question: why wiki? There are other good ways of
writing documentation, just to name: man-pages, GNU info (I have no idea
what's that and how to use that and just freak out when a tool's man page
says “for more details check the info”), plain text files. But for some
reason wiki is widely used. Do you know why? I don't. But won't it be the
case that by moving wiki editing to the console you'll break this magical
wiki charm that makes people write articles?

Anyway, this sounds like a great project: wiki backed by markdown+VCS
instead of MediaWiki markup+database. I like the idea, and here are the
good news: this thing already exists! https://github.com/gollum/gollum
Even more awesome: https://github.com/jgm/gitit.

So, basically, I can extract three separate goals from your large text:

* Get rid of MediaWiki to make it possible to edit articles in text
editors. Solution: migration to Gitit.
* Create a Nix expression that will checkout HEAD of the wiki repository
and prepare it to be deployed locally (web server serving wiki). Solution:
create it, but after Gitit migration.
* Better documentation. Solution: ???.

Now to the main point. I doubt that it's possible to get a good
community-written wiki by enforcing some kind of policy (like, ”DO write
articles, and DO write _good_ articles”). I think, everyone agrees that the
best Linux wikis out there are Gentoo Wiki and ArchWiki and I'm not sure
that they became so awesome because someone wanted them to. It all happens
automagically once there is a critical mass of users. I'm afraid that there
are just not many enough NixOS users to have a really good wiki right now.
But, yeah, we can try at least.

P.S. I'm not sure that NixOS wiki is a good place to this “For The
Uninitiated” page. I don't know, maybe linux.about.com or StackOverflow?

--
Кирилл Елагин

On Mon, May 19, 2014 at 10:33 AM, Third3ye <tredje0ye at gmail.com> wrote:

>  Hey there!
>
> I'm Third3ye and you've probably seen me troll the #NixOS channel like a
> pro. If you don't want to read this rather large e-mail about the wiki, how
> about answering a few questions?
>
>    1. *Do you edit or add to the Wiki? If so how frequently?*
>    2. *Would you like to see the Wiki expanded upon?*
>    3. *Would you prefer an alternative way of editing Wiki pages, say
>    through a terminal or through github?*
>
> Now, on with the talky-talk...
>  Lately I've been talking to Chexxor and have been looking for a way to
> contribute while I get to learn nixpkgs, C++ and QT to work on a more
> ambitious project. I've worked within computer management, UX research,
> web-design, GUI design and a wee bit of scripting/programming in projects,
> small and mid-size businesses --- yet I have much MOAR to learn (I need
> moar...!)
>
> Chexxor has let me know that he is currently undergoing (a seemingly
> undermanned) restructuring of the NixOS Wiki. I've decided to throw my hand
> in to this by doing one thing and suggesting another: contributing
> individually to the Wiki and to start a project of automating the
> assembling and building of the wiki, including data (but excluding
> userbase), through nixpkgs.
>
> The reason behind the suggestion is that the NixOS ecosystem is perfect
> for deployment, especially within intranet scenarios (nix+hydra+disnix? Yes
> please). Unfortunately you are often left without direct access to internet
> in these cases (due to security). You're then often forced to use your
> phone or get to a computer that has access to internet.
>
> The Wiki for Linux distribution is in some cases the only manual or a
> great source of extra information regarding special scenarios. It is also a
> go-to source for maintenance, installation and configuration within these
> special scenarios. The idea is to create a nixpkg that automatically builds
> the NixOS wiki and that can import updated wiki pages via a simple update
> through nixpkgs.
>
> But the problem is the Wiki needs updating and this needs people to add
> the relevant information. I'm guessing here, but I'm pretty sure that most
> maintainers and pullers more often than not forgo adding extra information
> to the Wiki that might not have a home in the manual. This is probably due
> to the fact that this means involving another system of publishing and
> maintaining data (visa vi using the WikiMedia interface and engine). I
> suggest we bridge that gap and make nixos-wiki an ad-hoc version of the
> Wiki that can be built and deployed anywhere.
>
> This can be done in two ways:
>
>    1. including a "doc.wiki" (or similar) expression that allows adding
>    data to the relevant to a page and section of the Wiki. This would
>    effectively remove any necessity for a developer or maintainer to move
>    beyond the nixpkgs system, which I think is the most effective approach.
>    But this would also mean adding code to nix, which I'm not sure will be the
>    preferred choice.
>    2. Making a simple pkg that has a folder structure similar to the
>    structure of the wiki. default.nix would then serve as an index file and
>    wiki pages would simply be markdown files. A developer/maintainer could
>    then just add to the wiki page from terminal and commit for review.
>
> The reason I suggest these options is because I think that the Wiki needs
> some serious attention and is in dire need of a restructuring. I think that
> by starting the discussion of including the wiki maintaining process as a
> package or as a part of nix expression would be a good start to find
> alternative ways of including people in the Wiki editing process.
>
> Additional additionally!
> I've created a few pages and would like some feedback from the community
> in regards to subject and structure. Here are the pages:
>
> *The UDX initiative*:
>     https://nixos.org/wiki/UDX_Initiative
> *For the uninitiated* (a cheat-sheet in regards to Linux/Unix and Nix(OS):
>     https://nixos.org/wiki/For_The_Uninitiated
> *KDE* (example of a simple wiki page):
>     https://nixos.org/wiki/KDE
>
> *"The UDX inititative"* is a theoretical approach to the user & developer
> relationship and how to most effectively facilitate the processes between
> them. In the FOSS world there are many initiatives and movements within
> these parameters. I think it would be a good idea to assemble some of these
> ideas in to a page that is ment to teach both users and developers how to
> achieve an optimal state of productivity.
>
> *"For the uniititated"* is something I'm working on because I never took
> the time to learn sed, gawk, regular expressions, and so forth. I intend to
> add more to this page while I learn how to effectively use these commands.
> Btw: is cut apart of stdenv? Like I said: I'm still learning, so MY wiki
> editing will be slower than hell so that I don't provide misinformation.
>
> *"KDE"* serves as a temporary playground for illustrating how to make
> simple, semantic and to-the-point Wiki pages that contain uniform layout,
> structure and illustrations. By focusing on these tenants the reading of a
> Wiki page can become incredibly potent in it's ability to teach ideas,
> concepts and functionality.
>
> The point of all these pages is to not just start a discussion around
> adding data to the WIki, but *how* you add data to the wiki or
> documentation in general. If it can be easily understood by anyone (and I
> mean anyone) and if the Wiki can serve as "Linux/NixOS for dumbies"... I
> know I need it in my shelves - ehr, nixpkgs. Visa vi the UDX initiative is
> my own spin on UX. Since UX deals purely with the concept of a user and not
> the developer it is biased towards the concept of a "professional" (or at
> least for-profit) service and environment. But in the open source
> environment and within FOSS software the costumer (or "user") is not
> "always right and the developer is not paid (directly) for their efforts.
> As such there needs to be guidelines to facilitate easy, effective and
>
> Therefor a consensus is required between the two. I think this is a
> natural step in the right direction for FOSS software as we need to cater
> to the environment and conditions of FOSS software which are not the same
> as the commercial counterparts.
>
> I've been Third, rambling as usual...
> Thanks for reading!
>
> _______________________________________________
> 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/20140519/f80a01a1/attachment.html 