[Nix-dev] Restructuring of the Wiki

[Third3ye]

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!

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20140519/a29766f1/attachment.html