[Nix-dev] Restructuring of the Wiki

Mon May 19 13:13:04 CEST 2014

On 05/19/2014 10:03 AM, Kirill Elagin wrote:
> 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.

Pandoc seems to be a popular choice outside of Haskell community too.

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

It's true that there are other ways to provide documentation, but the
appeal of wiki is that all you need is a browser and we've all used
wikipedia before. It's easy to edit (don't need to send patches
somewhere then wait), easy to distribute and easy to view.

Granted, browsers nowadays are not the most light-weight things but most
of us use one.

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

I agree that rather than there being some technical reason for why
Gentoo wiki is much bigger and complete than NixOS wiki is simply the
number of users. Also notably, Gentoo offers a lot of customisation so
the wiki often has to go in depth about different setups, which is great!

> 
> 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
>>
>>
> 
> 
> 
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
> 

-- 
Mateusz K.