Category:Pedias: Difference between revisions

From NixOS Wiki
← Older editNewer edit →
VisualWikitext
imported>Ixxie
imported>Ixxie
Added style section.
Line 1: Line 1:
Discussions are ''understanding-oriented'' articles aimed at explaining a particular topic. They are encyclopedic, intended to provide an overview of the subject at hand, illuminating the big picture and various perspectives of it. A discussion article might be read casually for leisure, rather than being used as [[:Category:Reference|reference]] while coding.
Discussions are ''understanding-oriented'' articles aimed at explaining a particular topic. They are encyclopedic, intended to provide an overview of the subject at hand and various perspectives of it. A discussion article might be read casually for leisure, rather than being used as [[:Category:Reference|reference]] while coding.


==Style==
== Style ==


===Language===
Besides the [[Contributing to the Wiki#Style|general style considerations]], discussion articles should be written with the following considerations in mind:


Discussion articles should be written in clear, standard and professional language. To this end, the following considerations apply:
* ''Accessibility'': discussions are often the first thing a new user will read about any subject, so they should be accessible to beginners.
 
* ''Overview'': discussions must provide a clear overview of their subject matter, and be accordingly organized into easily navigable sections.
* ''Vocabulary'': use the simplest and most conventional words and expressions you can find to get your point across without oversimplifying.
* ''Variety'': related to the previous point, where appropriate discussions should cover multiple workflows, approaches and perspectives to the topic.
* ''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.
* ''Code'': code examples should be cogent and illustrative of the surrounding text (otherwise they would normally go in one of the other article types).


==Canonical Forms==
==Canonical Forms==

Revision as of 11:03, 30 August 2017

Discussions are understanding-oriented articles aimed at explaining a particular topic. They are encyclopedic, intended to provide an overview of the subject at hand and various perspectives of it. A discussion article might be read casually for leisure, rather than being used as reference while coding.

Style

Besides the general style considerations, discussion articles should be written with the following considerations in mind:

  • Accessibility: discussions are often the first thing a new user will read about any subject, so they should be accessible to beginners.
  • Overview: discussions must provide a clear overview of their subject matter, and be accordingly organized into easily navigable sections.
  • Variety: related to the previous point, where appropriate discussions should cover multiple workflows, approaches and perspectives to the topic.

Canonical Forms

While in general, discussion articles can take a wide variety of forms, certain types of articles recur in the NixOS wiki and warrant specific formats. For these we provide canonical forms, recommended templates for structuring these types of discussion articles.

Software

Software articles cover a software package, application or library. The following structure is recommended for such articles, with the first sections considered most critical:

  1. Introduction: a general overview.
  2. Usage: a practical overview of different approaches to installing, configuring and operating the software, linking to more comprehensive guides.
  3. Internals: a theoretical overview of the internal architecture of the software, including critical files and directories, processes and objects.
  4. Development: a project overview for potential contributors, including an overview of the source-code directory structure, development process, issue tracking and the developer community.
  5. History: a historical overview of the software, including an overview of the origins and past development of the software, and the broader historical context, such as precedents and antecedents.
Retrieved from "https://wiki.nixos.org/w/index.php?title=Category:Pedias&oldid=2853"