|
|
| (17 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| This article is a guide to contributing to the Wiki. Contributors are encouraged to write new articles or modify existing ones as they see fit, but it is appreciated and encouraged to follow the recommendations of this guide as for as possible whenever they are applicable.
| | #Redirect [[Contributing]] |
| | |
| == Spirit of the Wiki ==
| |
| | |
| The NixOS User Wiki is a ''community'' effort, meant to be complementary to the manuals rather than a replacement for them. The following properties distinguish the spirit of the Wiki from that of the official documentation:
| |
| ; Ecosystemic: The manuals cover specific software (Nix, NixOS, etc.) while the Wiki covers the Nix ecosystem as a whole, helping the user understand the interrelations more clearly.
| |
| ; Heterogeneous: The manuals normally give one canonical approach to something, the Wiki has the potential to reveal the more diverse approaches and workflows used in practice.
| |
| ; Pragmatic: The manuals are intended for comprehensive and detailed reference, while the Wiki could emphasize practical and learning resources such as guides, tutorials and cookbooks.
| |
| ; Networked: The manuals are ''sequential'' with one chapter following another while the Wiki is ''networked'', with various articles linked to one another in various ways, allowing the user to reach information in multiple ways.
| |
| ; Community: The manuals cover the more official and stable core of the Nix ecosystem, while the Wiki can cover the whole Nix community with its diverse projects and communication channels.
| |
| | |
| == Finding stuff to do ==
| |
| | |
| The following are ways to find out (or let people know) what needs to be done:
| |
| * Use the [https://github.com/nixos-users/wiki/projects Wiki Projects] page to list or join a project and the [https://github.com/nixos-users/wiki/issues Wiki Issues] page to raise issues and find stuff to do.
| |
| * Help improve flagged articles in the appropriate way.
| |
| * Fill out missing articles linked anywhere ([[Special:WantedPages]]), and missing sections in any article.
| |
| * Write [[:Category:Tutorial|tutorials]] and [[:Category:Guide|guides]] to help ease pain-points for beginners.
| |
| * Check the [http://lassul.us/wiki-todo Wiki To-Do List].
| |
| | |
| == Style ==
| |
| | |
| | |
| === Language ===
| |
| | |
| NixOS Wiki articles should be written in clear, standard and professional language. To this end, the following considerations apply:
| |
| ; Accessibility: Wiki articles are often the first thing a new user will read about any subject, so they should be accessible to beginners.
| |
| ; Vocabulary: Use the simplest and most conventional words and expressions you can find to get your point across without oversimplifying.
| |
| ; Organization: Keep your text structured in coherent sentences, paragraphs and sections, each with its own clear themes and topics.
| |
| ; Citations: Citations aren't required, but definitely appreciated; when citing code, hardlink to a particular revision.
| |
| ; Attribution: Where external material is quoted or utilized in the article, and/or licensing or common sense demands it, place clear and complete attribution and (where possible) a link.
| |
| | |
| === Syntax ===
| |
| | |
| Make sure to:
| |
| * Follow standard capitalization for software, particularly for the Nix ecosystem (NixOS, Nix, Nix Language, Nixpkgs, NixOps and Hydra).
| |
| * Use inline <code><nowiki><code></nowiki></code> tags for filenames, paths, commands and command-line tools.
| |
| * Use <code><nowiki><syntaxhighlight lang="nix"></nowiki></code> for code snippets. Change <code>lang=</code> to match the actual language of the code.
| |
| * Use the secondary MediaWiki header (<code><nowiki>== My Section ==</nowiki></code>) for main sections (the primary header should never be used).
| |
| | |
| === Code ===
| |
| | |
| Articles can and often should contain plenty of code snippets and blocks. When using code consider the following:
| |
| ; Quantity: Code examples should be minimal, to-the-point, and only used when illustrative of the surrounding text.
| |
| ; Style: Code should be properly indented with clear naming and commenting where necessary.
| |
| | |
| == Tagging articles ==
| |
| | |
| The MediaWiki provides a way to tag articles (at the end of the article). We are using this feature to structure the Wiki.
| |
| | |
| === Ecosystem tags ===
| |
| | |
| Elements of the Nix Ecosystem should be tagged by one or more of the following categories:
| |
| ; <code>[[:Category:NixOS|<nowiki>[[Category:NixOS]]</nowiki>]]</code>: Articles related to the Nix Operating System, the Module System and the System Configuration.
| |
| ; <code>[[:Category:Nix|<nowiki>[[Category:Nix]]</nowiki>]]</code>: Articles about Using the Nix Tools to accomplish great things.
| |
| ; <code>[[:Category:Nixpkgs|<nowiki>[[Category:Nixpkgs]]</nowiki>]]</code>: Articles about Maintaining code in the Nixpkgs repository, structuring, and so on.
| |
| ; <code>[[:Category:Nix Language|<nowiki>[[Category:Nix Language]]</nowiki>]]</code>: Description of Language quirks and solutions.
| |
| ; <code>[[:Category:NixOps|<nowiki>[[Category:NixOps]]</nowiki>]]</code>: Articles about [https://github.com/NixOS/nixops the NixOps tool] and ecosystem.
| |
| ; <code>[[:Category:Hydra|<nowiki>[[Category:Hydra]]</nowiki>]]</code>: Articles about Hydra continuous Integration related documentation.
| |
| ; <code>[[:Category:Disnix|<nowiki>[[Category:Disnix]]</nowiki>]]</code>: Articles about Disnix, the Nix-based microservice architecture.
| |
| ; <code>[[:Category:Application|<nowiki>[[Category:Application]]</nowiki>]]</code>: Articles about other Nix-based or Nix-related applications.
| |
| | |
| === Resource tags ===
| |
| | |
| The [https://www.divio.com/en/blog/documentation/ type of documentation] for new pages should be tagged with one of the following categories:
| |
| ; <code>[[:Category:Tutorial|<nowiki>[[Category:Tutorial]]</nowiki>]]</code>:
| |
| :* is learning-oriented
| |
| :* allows the newcomer to get started
| |
| :* is a lesson
| |
| ; <code>[[:Category:Discussion|<nowiki>[[Category:Discussion]]</nowiki>]]</code>:
| |
| :* is understanding-oriented
| |
| :* explains
| |
| :* provides background and context
| |
| ; <code>[[:Category:Guide|<nowiki>[[Category:Guide]]</nowiki>]]</code>:
| |
| :* is goal-oriented
| |
| :* how-to's for dealing with a specific problem / tool
| |
| :* is a series of steps
| |
| ; <code>[[:Category:Cookbook|<nowiki>[[Category:Cookbook]]</nowiki>]]</code>:
| |
| :* is recipe orientated
| |
| :* a collection of short code snippets and hacks
| |
| :* arranged around a theme or tool
| |
| ; <code>[[:Category:Reference|<nowiki>[[Category:Reference]]</nowiki>]]</code>:
| |
| :* is information-oriented
| |
| :* describes the machinery
| |
| :* is accurate and complete
| |
| :* Most of the time the NixOS Wiki will not contain reference documents
| |
| | |
| == References ==
| |
| | |
| * [https://www.divio.com/en/blog/documentation/ Types of Documentation]
| |
| * [https://github.com/nixos-users/wiki/issues/3 Wiki Restructuring Discussion]
| |
| | |
| [[Category:Guide]]
| |
