Category:Pedias: Difference between revisions

(21 intermediate revisions by 2 users not shown)

Line 1:

~~Discussions, or explanations, clarify and illuminate a particular topic. They broaden~~ the ~~documentation’s coverage of a topic~~.

''Pedia'' is one of the five primary [[Resources|resource]] categories for the wiki.

~~They~~ are '''understanding-oriented'''.

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

~~Discussions can equally well~~ be ~~described~~ as ~~explanations~~. ~~They are~~ a ~~chance~~ for the ~~documentation~~ to ~~relax~~ and ~~step back from~~ the software, ~~taking~~ a ~~wider view~~, ~~illuminating it from~~ a ~~higher level~~ or ~~even from different perspectives~~. ~~You might imagine~~ a ~~discussion document being read at leisure~~, ~~rather~~ than ~~over the code~~.

=== Writing Pedias ===

Besides the [[Manual of Style|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 [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]]

@@ Line 1: / Line 1: @@
-Discussions, or explanations, clarify and illuminate a particular topic. They broaden the documentation’s coverage of a topic.
+''Pedia'' is one of the five primary [[Resources|resource]] categories for the wiki.
-They are '''understanding-oriented'''.
+''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.
-Discussions can equally well be described as explanations. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code.
+=== Writing Pedias ===
+Besides the [[Manual of Style|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 [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]]