Devuan Documentation Guidelines 🔼

  • general explanation
  • notes

Official Documentation 🔼

  • general explanation
  • subchapters
  • notes

Structure 🔼

  • general explanation

While the (users') manual would be the general 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 (getting-task-done documents). A development docs section could simply inherit that typology.

What are the differences, again?

  • The manual covers "it all" (how to get, install, configure, use the system), but only on a basic level.
  • Guides provide more indepth ("theoretical") coverage of specific topics (e.g. networking) on the basis of which the reader [will be able to]/[can] make informed decisions on his or her own. (enable)
  • Howtos cover 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.
  • notes

Devuan Manual 🔼

The Devuan Manual is the general reference point for "everything you need to know"/how(where) to obtain/get, install and run a Devuan system.

  • 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
  1. In short: how to properly set up and operate a Devuan system (Well, that's part one, right).
  • The Manual covers it all (Define "it")/generally covers the Devuan system (except development), but not en detail, however, detailed enough to get basic setups working.

Naming and versioning

  • Manuals always relate to a major release version.
  • Naming scheme for Devuan Manuals: Devuan [MAJOR RELEASE VERSION].x ([RELEASE CODE NAME]) 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

Notes

  • The devuan Manual is structurally equivalent to Debian's installation guides (cf. https://www.debian.org/releases/stable/installmanual)
  • The Jessie manual shall be used as a blueprint for Devuan manuals in general (except development).
  • If there were to be a Devuan Devs' Manual, this manual (the users'
  1. would still be the overall central reference point because before engaging in developing Devuan, you first need to/should better (know how) to get, install, run/maintain it -- even if you were to develop Devuan-related stuff on an entirely different system.

Guides 🔼

  • TLDP says: "longer, in-depth books"1 Avoid the term 'book'.
  • Oxford Advanced Learner's Dcitonary also mentions: "something that gives you enough information to be able to make a decision about sth or form an opinion"2
  • a howto, on the contrary, would be more pragmatic in putting down a reasonable way to do things, largely leaving out detailed backgroudn
    1. a guide should enable the reader to do exactly that him or herself by providing such information.
  • 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 🔼

  • Debian says: "The HOWTO documents, like their name says, describe how to do something, and they usually cover a more specific subject."3
  • TLDP says: "subject-specific help"4 and "HOWTOs are detailed 'how to' documents on specific subjects" [^5]
  • focus:
  • specific task
  • how to get things done

Developers' Documentation 🔼

Meta Documents 🔼

  • Devuan Documentation Guidlines
  • Devuan Documentation Roadmap

Development & Release 🔼

  • (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.
  • https://github.com/Git-Mediawiki/Git-Mediawiki
  • (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).
  • Documentation release formats
  • Official documentation that is ready for use shall be made available in the following formats:
    • PDF
    • HTML (for online reading)
    • HTML (zip-ed, single file(?) -- for downloading and offline
    • plain text (single file -- for offline reading in non-graphical
    • Which encoding should be used?

Presentation 🔼

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

Manuals 🔼

The root page for the Devuan manual should contain a list of links pointing to the manuals for different releases. These should then be available in plain text, HTML and PDF format as well as in different languages.

Community Documentation 🔼

Licensing 🔼

  • (blinkdog) [...] the CC-BY-SA 4.0 license would allow us to do a GNU documentation share-and-share-alike. 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.
  • https://creativecommons.org/licenses/by-sa/4.0/
    • devuan.org is already using that license
  • Going with CC-BY-SA 4.0 as the main doc license, meaning:
  • It will be the sole license for the Devuan Manual.
  • It will apply to all contributions made through the Devuan Wiki.
  • Copyright holder of the Manual shall be Dyne.org Foundation
    * List authors with year(s) of contribution
  • There shall be one license per individual document (Manual, Guide,
  • Authors of guides and howtos may freely choose a license different from but compatible to the CC-BY-SA 4.0 license for their
  • Devuan will, however, recommend CC-BY-SA 4.0 and possibly also make recommendations for authors who want to or have to use another

Unsorted 🔼

  • Try to limit the number of individual documents to a managable amount (for pepole using Devuan's docs)
[^5]: http://tldp.org/docs.html#howto, 2017-11-25

  1. http://tldp.org/, 2017-11-25 ↩

  2. Oxford Advanced Learner's dictionary of Current English, 6th edition, OUP 2000, p. 572 ↩

  3. https://www.debian.org/doc/#howtos, 2017-11-25 ↩

  4. http://tldp.org/, 2017-11-25 ↩