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.
Besides the general style considerations, discussion articles should value:
- Discussions are meant to provide a clear overview of their subject matter, and be accordingly organized into easily navigable sections.
- Discussions should cover multiple workflows, approaches and perspectives to the topic.
- Discussions 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, discussion 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.