Category:Pedias: Difference between revisions

Latest revision as of 20:05, 2 September 2024

Pedia is one of the five primary resource categories for the wiki.

Pedias (abbreviation of "encyclopedia") 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 pedia article might be read casually for leisure, rather than being used as reference while coding.

Writing Pedias

Besides the general style considerations, pedia articles should value:

Overview: Pedias are meant to provide a clear overview of their subject matter, and be accordingly organized into easily navigable sections.
Diversity: Pedias should cover multiple workflows, approaches and perspectives to the topic.
Focus: Pedias should maintain focus on the subject at hand, linking to other resources such as dedicated articles when a section starts running too long.

While in general, pedia articles can take a wide variety of forms, the following canonical form is designed for articles covering a software package, application or libraries, and will often be applicable in the NixOS Wiki:

Introduction: a general overview.
Usage: a practical overview of different approaches to installing, configuring and operating the software, linking to more comprehensive guides.
Internals: a theoretical overview of the internal architecture of the software, including critical files and directories, processes and objects.
Development: a project overview for potential contributors, including an overview of the source-code directory structure, development process, issue tracking and the developer community.
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.

Comparison to other resource page types

If information is less encyclopedic and more similar to a compendium, study guide, or a bibliographic guide, a page would be considered a guide.
If information is more about direct instruction to achieve a specific task, a page would be considered a tutorial.
If a page is more just a set of tips and tricks (less instructive than a tutorial), it would be a cookbook.
If a page is a detailed reference (like a man page or full software manual), it would fit under references.

Pages in category "Pedias"

The following 20 pages are in this category, out of 20 total.

@@ 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.
+''Pedia'' is one of the five primary [[Resources|resource]] categories for the wiki.
-==Style==
+''Pedias'' (abbreviation of "encyclopedia") 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 ''pedia'' article might be read casually for leisure, rather than being used as [[:Category:Reference|reference]] while coding.
-===Language===
+=== Writing Pedias ===
-Discussion articles should be written in clear, standard and professional language. To this end, the following considerations apply:
+Besides the [[Manual of Style|general style considerations]], pedia articles should value:
-* ''Vocabulary'': use the simplest and most conventional words and expressions you can find to get your point across without oversimplifying.
+; Overview: ''Pedias'' are meant to provide a clear overview of their subject matter, and be accordingly organized into easily navigable sections.
-* ''Organization'': keep your text structured in coherent sentences, paragraphs and sections, each with its own clear themes and topics.
+; Diversity: ''Pedias'' should cover multiple workflows, approaches and perspectives to the topic.
-* ''Citations'': citations aren't required, but definitely appreciated; when citing code, hardlink to a particular revision.
+; Focus: ''Pedias'' should maintain focus on the subject at hand, linking to other resources such as dedicated articles when a section starts running too long.
-* ''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==
+While in general, ''pedia'' articles can take a wide variety of forms, the following ''canonical form'' is designed for articles covering a software package, application or libraries, and will often be applicable in the NixOS Wiki:
-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:
 # ''Introduction'': a general overview.
@@ Line 26: / Line 18: @@
 # ''Development'': a project overview for potential contributors, including an overview of the source-code directory structure, development process, issue tracking and the developer community.
 # ''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.
+=== Comparison to other resource page types ===
+* If information is less encyclopedic and more similar to a [https://en.wikipedia.org/wiki/Compendium compendium], [https://en.wikipedia.org/wiki/Study_guide study guide], or a [https://en.wikipedia.org/wiki/Guide_to_information_sources bibliographic guide], a page would be considered a [[:Category:Guide|guide]].
+* If information is more about direct instruction to achieve a specific task, a page would be considered a [[:Category:Tutorial|tutorial]].
+* If a page is more just a set of tips and tricks (less instructive than a tutorial), it would be a [[:Category:Cookbook|cookbook]].
+* If a page is a detailed reference (like a man page or full software manual), it would fit under [[:Category:reference|references]].
+[[Category:Resource]]