Notes & Discussion 🔼

Official Documentation 🔼

Structure/Typology 🔼

Devuan Manual 🔼

*Question: **Do we need port-specific manuals like Debian has them?** (And what would be the generic parts then?) Asking about how these differ in #debian, I got this answer: "the parts where hardware or firmware, esp. boot firmware is different". "many systems can't boot from cd or usb media, others can't boot from network, some need media prepared with the specific model in mind", "some don't have serial consoles, some don't have graphic cards at all", "some only work if you provide crazy non-free firmware".   -- msi

Guides & Howtos 🔼

  • Ideas on versioning of guides and howtos:
  • Update them when they need updating, but always keep around copies of the latest versions for respective stable release prior to the current one. (If ASCII gets out, keep the latest version for Jessie availabe and so on.)
  • Problem: Versions of guides and howtos not being in sync with Devuan
    • How can we deal with that?
    • At least guides could be released as specific to major releases, even if that could mean mostly copying things over in some
    • Or (and preferably): $author/$maintainer keeps track of which versions apply to what release, so they can be placed
    • For example: ASCII's docs could include a Devuan Apt Guide v1.0 at the beginning of its life time and v1.4 at it's end. Then, if there are no changes to be made to the document in order to still be accurate for Beowulf, Beowulf docs would include v1.4, and if there were, include v1.5 or v2.0 at the beginning...

Developers' Documentation 🔼

Several possible ways to include this 🔼

  • One: A Devuan Developers' Manual (next to the users' manual) as a central point of reference for devs + sections for development stuff in Guides and Howtos (Devuan Manual should then be renamed Devuan Users' Manual)
  • Two: A separate Developers' Documentation section offering a collection of Guides and Howtos etc. (e.g. for packagin, amprolla etc.)
  • Three: A serapate Developer's Docuemntation section, offering a Devs manual as a central point of reference plus a collection of development guides and howtos
  • We would only really have to decide between option one and two or three, since two and three are not mutually exclusive (two might grow into three). I think two/three would be the best solution. --msi
  • Seems, we're going with option two/three
  • Would a Developers' manual have to be release-specific in any way?

Documenting different releases 🔼

  • stable, testing, ceres branches in the docs (the last two primarily a collection of caveats? (see below))
  • (msi) packages.debian.org has a row of links for selecting the Debian release (repo) you want to find packages for at the top of the page. This would also be pretty convenient on a Devuan documentation landing
  1. You could have "Jessie"/"1.x", "ASCII"/"2.x" and so on to select from, current "stable" being the default.
  • On doc.devuan.org, there should be links ("oldstable") "stable", "testing", "unstable", pointing to their respective equivalent as per the current state of affairs. (Debian has that, too.)
  • (golinux) Using those terms for Devuan is risky because we will often find ourselves behind Debian. Currently we have no 'testing' branch available.
  • (chillfan) Maybe it would be better to go just by release codenames then, and give an explanation of each branch in their sections. We don't want to confuse ascii with Debian testing, etc.
  • (msiism) Ok, I didn't have this in mind. So, let's not do that now, but keep it on the road map, shall we?

Documenting Testing and Ceres 🔼

  • (msi) As there are usually a lot of questions on "testing" (or even "unstable"), there should be a place to put interim documentation on
  1. It's probably best to have that on the wiki, since there will be a lot of moving parts (installation methods not being ready yet, but becoming ready and so on). But where on the wiki?

Documentation and point releases 🔼

Parts of the Manual will have to be updated on point releases.

Suggestion: Don't keep pre-point-release docs around publicly. For example: If 1.1 is released, don't keep the 1.0 docs around for public access (maybe keep an internal copy). Everyone not upgrading for no good reason will be on an unsane path.

  • (msi) The Devuan Manual should always correspond to respective the major release version only. (That's how Debian does it.) If parts of it should need updating after a point release (which, I guess, should rarely be the case), update it. There is, however, no need for point-release specific manuals, as the system will normally be brought up to the latest through routine upgrades. Everyone not upgrading for no good reason will surely be on an unsane path.
  • (msi) Having as many versions of the Manual lying around as there are point releases will most certainly lead to a good deal of
  • (msi) Necessary adjustments to non-trivial parts of the Manual could be made by inserting notes into a given Manual, like: "Note: As of Devuan version 1.3, this and that..."
  • (msi) All the above is probably saved by having the Manual versioned through revisons, like: Devuan 1.x (Jessie) Manual, Rev. 1
  • (msi) We may or may not keep older revisions around publicly then.
  • (msi) But what we should keep around is a channgelog. That should actually be part of the Manual itself.

Presentation 🔼

  • beware that devuan.org/os/documentation already exists
  • (golinux) Basic essential documentation should stay on devuan.org/os/documentation but content could be expanded or tweaked and have a prominent reference to the wiki once it is fleshed out a bit more. It is poor form to send someone off-site for basic
  • (msiism) I don't see the point of keeping it around. It's content could be integrated into the doc.devuan.org landing page. Also, I wasn't able to find a way to get there from devuan.org's navigation
  1. Plus: The exact same content is also on devuan.org/os. But if you really want to keep it, so be it. (Structure of the website is another discussion.)
  • (golinux) - AFAIK there is not even a placeholder for doc.devuan.org And IMO we do not have enough docs yet to warrant it.
  • (blinkdog) As I understand Search Engine Optimization, it's OK to move content around, but the important point is not to duplicate content over many URLs (old URLs should redirect to new ones), otherwise the weight gets divided between pages, and sinks all of them in the search rankings. But, if we choose a canonical location and make sure we refer to it, the engines will reindex our content well when they crawl our site(s) again.

Things to (possibly) include as well (later) 🔼

Devuan FAQ 🔼

  • Do we really need this? Chances are, it will end up being a whole lot of not-so-well-structured duplicate documentation.
    1. https://www.debian.org/doc/manuals/debian-faq
  • Where to put it, in case it's going to be there? On the docs landing

Misc 🔼

  • something like https://www.debian.org/doc/#other
  • "Getting started" section
  • Basically, a concise summary of the installation guide to get you up and running fast
  • probably better call that "Quick start", since "Getting started" pages usually seem to have another function (cf. Firefox and Debian)
  • they usually provide an overview of what you can do and where to find what
  • look at what "Getting started" is in Debian
  • Debian has an „Installation Howto" in the appendix to its installation manual for this purpose
  • Lists of software available in Devuan sorted per task (like media players, burning a cd, wifi, web browsing, graphics and publihing etc. see https://wiki.debian.org/Software, https://wiki.ubuntuusers.de/Software or https://wiki.archlinux.org/index.php/List_of_applications)
  • probably better placed in the community docs
  • administration and user manuals (make those sections in the manual)
  • keeping the system up-to-date
  • managing user accounts
  • sharing files in a workgroup
  • basic networking
  • basic security

Including things into the official documentation 🔼

  • If it's not in any way specific to Devuan, don't include it. Configuration guides for window managers are, for example, not Devuan-specific, so they should go to the community wiki (preferably) or into the d1g forum.

Forking Debian (& other) Documentation 🔼

  • Debian's install manuals are licensed GPLv2
  • What does copying/forking require?
  • Are there any restrictions on using GPLv2-licensed stuff and relicensing it under the GFDL 1.3?

Devuan Wiki 🔼

  • What role is this wiki going to play?
  • development platform for official Devuan docs
  • Community wiki: Thoroughly maintained community documentation (like Arch Wiki) or laissez-faire (like Debian's wiki)?

Licensing 🔼

  • (msi) The list of licenses officially compatible to CC-BY-SA 4.0 can be found at: https://creativecommons.org/share-your-work/licensing-considerations/compatible-licenses
  • (msi) There are only two licenses in there, with one (GPLv3) not being recommended, the other one being the Free Art license 1.3.
  • (msi) A look into the cc-licenses mailing list archives shows that no other licenses are currently being reviewed.
  • (msi) In effect, this boils down to having either the CC-BY-SA- 4.0 or the Free Art License 1.3 to choose from when contributing to Devuan's documantation, if everything is to be compatible to the
    1. Both of them are copyleft licenses.
    • (msi) Should we allow free licenses without copyleft for individual documents in the Guides and Howtos sections?

Notes 🔼

  • Try not to reinvent the wheel. If there is quality (official) documentation on something, link to it (or fork it, if necessary).