<!-- vim: set tw=78 sts=2 ai expandtab: -->
# Reminder to update the English RAWXML/* files

2024-02-02T00:45:26 UTC

Osamu Aoki, <osamu at debian dot org>

## Is there easier way to edit XML source

Unfortunately, no.

## Selection principles for the content

Debian Reference starts in with:

This Debian Reference is intended to provide a broad overview of the Debian
system as a post-installation user's guide. It covers many aspects of system
administration through shell-command examples for non-developers.

Also, in its appendix "A.1. The Debian maze", it states:

... There are also references called HOWTO and mini-HOWTO. They are easier to
understand but tend to give too much detail and lose the big picture. I
sometimes have a problem finding the right section in a long HOWTO when I need
a few commands to invoke.

I hope this "Debian Reference" provides a good starting direction for people
in the Debian maze.

These should be the guiding principles.  Keywords are:

* a broad overview
* shell-command examples
* HOWTOs ... too much detail and lose the big picture
* problem ...  a long HOWTO
* a good starting direction

Please note "Debian Reference" isn't trying to give too much detail nor long
HOWTOs.

## Checklist questions

Let's ask ourselves several questions before adding any contents.

* Do they qualify as the minimum set of information which new Debian users
  should be exposed?
* Are they expressed in the shortest possible way?
* Can we use common text in table to reduce translation efforts?
* Are they actively used in the Debian infrastructure or in the popular
  sub-project such as freedombox, debian-edu, ...?
* Do I personally use them regularly (or previously)?
* Have I personally tested or inspected key features of programs to be
  mentioned in them, at least?
* Are they about actively maintained program? (No sourceforge.net upstream.)
* Are they the best/better program offering the feature?
* Are they about main stream program?
  * POPCON `V > 200` : popular and OK to add even if a similar package exists
  * POPCON `I > 5`   : OK to add if you used or tested it and found useful
  * POPCON `I = 0`   : Don't add unless you have strong arguments
* Are they about main stream working environment? (#1 GNOME, #2 KDE)
* Is there any strong reason to add them?
  * sysv to systemd transition -- mostly done
  * UEFI transition            -- mostly done
  * OAUTH2 support for SMTP/IMAP4 (future TODO)
  * lxd to incus transition (future TODO)
  * GNOME45 transition (future TODO)
* Is there any outdated content to drop?
  * CVS, SVN to Git transition -- mostly done
  * Old mail (MTA, etc.) contents -- mostly done
  * Old unused Exif data tools -- next AR

Use quoted XML comment `<!-- XML comment strings -->` to annotate decisions.

## Reminders for commit

Split commits as small change set as possible.

Automated conversion such as "make po" and "make entity" should be a separate
commit to make it easy to revert.

Osamu
