Devuan Documentation Guidelines

  • Thoroughly reviewed and signed off on by the Devuan doc team on release.
    • Every individual document released as part of the official documentation will be signed with the Devuan Documentation Team's GPG key and the signature provided with the documentation.

Structure

  • Devuan's official documentation includes the Devuan Manual, Guides, Howtos, the Devuan Developers' Manual as well as some meta documents, including these guidelines.
  • each of these documents serve different purposes
  • While the Manual would be the general/central reference point for what Devuan is, how to install and use it, Guides would deal with specific bigger topics (e.g. networking) en detail, while Howtos would be more pragmatic problem-solving oriented docs.

Devuan Manual

The Devuan Manual is the general reference point for “everything you need to know”/where and how to get, install (and configure) and run Devuan.

  • The Manual covers “it all”, but only on a basic level.
    • generally covers the Devuan system (except development), but not en detail, however, detailed enough to get basic setups working.
  • Content-wise, it focusses on – one – the things everyone needs to or should (better) know about Devuan in general and – two – on the things everyone needs to do to get, install and run/maintain a Devuan system. In short: how to properly set up and operate a Devuan system (Well, that's part one, right).

Guides

  • Guides provide more in-depth (“theoretical”) coverage of specific topics (e.g. networking) on the basis of which the reader will be able to make informed decisions on his or her own. (explain (thoroughly) and enable)
  • guides would deal with specific bigger topics (e.g. networking) en detail
  • While guides are meant to be more through and rather cover a specific topic than a specific task, that doesn't mean that they will necessarily be longer than Howtos. The distinction here is a question of what and how, not of how much.

Howtos

  • Contrary to Guides, Howtos are more pragmatic problem-solving oriented docs (getting-task-done documents).
  • pragmatic in putting down a reasonable way to do things, largely leaving out detailed background info
  • Howtos focus on how to practically get a specific task done in a reasonable way, providing only limited explanation on why it is reasonable to do it that way (no broader background).

Developers' Documentation

  • Description needed.

(This section could simply inherit the user doc's typology, if necessary.)

Meta Documents

  • What are they for?
    • Documenting the documentation.
  • Devuan Documentation Guidelines
  • Devuan Documentation Roadmap

Development, Release and Maintenance

  • (msi) Devuan's official documentation should primarily and preferably be developed on the official wiki, within a namespace that has the appropriate access restrictions.
  • (blinkdog) Those who wish to contribute to the wiki using Git as an interface can use the following plugin (for Git) that allows Git to understand how to talk to the MediaWiki API.
  • (blinkdog) Perhaps the documentation itself is curated from the wiki, written in MarkDown format, and we use `pandoc` to spit out the “official” PDFs that are then signed by the GPG keys of the documentation gurus (added to the devuan-keyring).

Devuan Manual

  • Manuals always relate to a major release version.
  • Naming scheme: Devuan [MAJOR RELEASE VERSION].x ([RELEASE CODE NAME]) Manual (E. g. “Devuan 1.x (Jessie) Manual”)
  • Don't entangle the version numbers of release-specific manuals with Devuan's release version.
    • Manuals will be versioned through revision numbers instead, as fsmithred suggested
      • (msi) This actually goes for every official document. See “Release Info” below.

Translations

Release Formats

Official documentation that is ready for use shall be made available in the following formats:

  • HTML
  • HTML (single-file)
  • PDF
  • Plain text (single-file)
    • Which encoding should be used? Probably UTF-8 Unicode.

Release Info

Every individual document shall carry release information in the following form:

[document title] [revision number] [date of publication]
The latest version of this document may be found at [find-latest-here url]

An example:

Devuan 1.x (Jessie) Manual, Rev. 6, 2018-12-24
The latest version of this document may be found at http://doc.devuan.org/manual

Presentation

  • Devuan's official docs shall be presented at doc.devuan.org, with devuan.org/doc(umentation) as a possible alias to that

Manuals

The root page for the Devuan manual should contain a list of links pointing to the manuals for different releases.

Scope

  • General guideline for including things into the official documentation: If it's not specific to Devuan in any way, don't include it. Configuration guides for window managers are, for example, not Devuan-specific, so they should go into the community wiki (preferably) or to the Documentation section of the Dev1Galaxy forum or wherever the author chooses to put them – and not into the “Guides” or “Howtos” section on doc.devuan.org.
    • (msi) What is specific to Devuan? Everthing that depends on how something is done within this distribution, e. g., installing packages through Apt etc.
  • This is where people can freely participate
    • Just do basic moderation: Remove vandlism and malicious content (malicious meaning: will very likely cause harm to the user's system (probably by intent)).
  • Where does it happen? In the community area of the wiki (preferably) or in the Documentation section at d1g.

Scope

  • Could cover anything that is related to Devuan. (Related to Devuan as in contrast to specific to Devuan (see scope of official docs above).)
  • (msi) People wanting to contribute guides, howtos or translations to the official documentation should be asked to use the wiki to do so.
    • (msi) It is (will) also (be) possible to contribute via Git, using the plugin mentioned above.
  • (msi) Authors should be asked to maintain their work. If they can't, someone else should be found. There should always be one or more mainatiner(s) for an individual document within the official docs.
  • (blinkdog) Independent contributions can be linked from the wiki. Standard symbols will show them as external links. Of course, if we can convince the author to import their content directly to the wiki, that's even better!
  • Discuss procedures for allowing access to new contributors

Attribution

Official docs

  • The author(s) of an individual document shall be listed with their name (real name or pseudonym) and year(s) of contribution right beneath the copyright notice of the document.
  • (blinkdog) […] the CC-BY-SA 4.0 license […][:] You have to maintain contributor history (which the wiki does automatically), but anybody is free to fork and remix the documentation, so long as they let others do the same.
  • Going with CC-BY-SA 4.0 as the main doc license, meaning it will aplly to
    • the Devuan Manual
    • the Devuan Documentation Guidelines
    • the Devuan Documentaion Roadmap
    • all contributions made to the Devuan Wiki
  • Copyright holder of the official docs shall be the Dyne.org Foundation
  • Exceptions for individual Guides and Howtos may be granted.
  • There shall be one license per individual document (Manual, Guide, Howto)
    • Authors of guides and howtos may freely choose a license different from but compatible to the CC-BY-SA 4.0 license for their contribution.
    • Devuan will, however, recommend CC-BY-SA 4.0 and possibly also make recommendations for authors who want to or have to use another license.
    • Devuan will also encourage transferral of the Copyright to Dyne.org.