[Nix-dev] Restructuring of the Wiki

[Mateusz Kowalczyk]

On 05/19/2014 08:33 AM, Third3ye 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?*

If I do something that's missing, I will add it.

>  2. *Would you like to see the Wiki expanded upon?*

Yes, there are definitely many pages missing. I had to create a page on
something as commonly used as NFS the other day!

>  3. *Would you prefer an alternative way of editing Wiki pages, say
>     through a terminal or through github?*

Can't say it's something I really miss, in the end one can copy + paste
from their text editor.

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


-- 
Mateusz K.