[Opendnssec-develop] Ideas for improving documentation

[Rick van Rein]

Hello,

As requested during the meeting, I would send a list of general and specific
things that I think could make the (online) documentation more accessible.

I hope it is useful -- I'll gladly edit whatever is considerd good stuff.

* People can land on any page, and may miss background.  For that reason,
  it is probably good to point back to general pages (such as Signer/Using)
  to indicate assumed prior reading.  Without it, people will be left
  wondering what KASP is (if not spelled out in each file on first use)
  and similar things.

* Scope on Signer/Using: This section should make the reader decide if it
  is worth reading on.  "OpenDNSSEC covers most of it" is not helpful to
  decide if it is saving the reader all concerns that s/he doesn't understand.

* Overview in Signer/Using: Here I am missing two things: 1. a list of
  software responsibilities and how they are assigned to components, which
  is really helpful to get an idea of what the terms mean; 2. a mapping
  of the components into how they are implemented (a few taken together
  as a daemon, a database like SQLite or MySQL, and so on).

  A quick brainstorm with the (user-experienced) responsibilities that
  could be useful to locate on components, as they constitute the path
  of a domain through the system (and tracing that would be helpful to
  see the flow for a new user):

   - knowledge of which zones are managed by OpenDNSSEC
   - knowledge of when each zone must be signed next time
   - generating, destroying and securely storing key pairs
   - managing key rollovers
   - responding to update notifications on a zone
   - fetching unsigned zone
   - controlling the timestamp in the SOA record
   - signing the records in a zone
   - inserting signed explicit holes (NSEC/NSEC3)
   - verifying if signing did not modify a domain
   - verifying if signing did not invalidate a domain
   - publishing the signed zone
   - submitting update notificates on a signed zone

  Also in Overview, it could help to introduce the term KSM as it is
  used in >1 other files without further indication of what it is.

* The Signer/Using splitup Installation / Configuration / Running (and
  perhaps Debugging) is pleasantly common.  I would suggest moving:
   - Platform support under Installation
   - Zone content under Configuration or Running
   - Command utilities under Running
   - FAQ and Reporting Bugs under Debugging

I've assumed Signer/Using is prior reading for the other documents.

* Using/Installation: No comments, very clear.  This may be a better place
  for the Platform support list than the more general Signer/Using?  After
  all, this is the file where one is working on "getting it going" whereas
  Signer/Using is about "what it means to be doing the OpenDNSSEC thing".

* Date/time durations in Signer/Using/Configuration: This is important but
  very detailed, and it is not very inviting at the start of this file, as
  it confuses the overview of this file (which IMHO is about guiding the
  reader around available configfiles).  I would have placed it at the
  bottom of the file, or even in a separate page for central reference.

* kasp.xml in Signer/Using/Configuration: What is a policy?  What sort of
  things can be configured in broad lines?  The use of this information
  would be to know what configfile to turn to if one wants to get something
  done.  The term "policy" is too general to new readers, I think, and so
  it could use a translation, a few examples, or both.

  Also in that section, "the hierarchical nature of XML allows the grouping
  of parameters into logical blocks" does not seem to add anything here.

* *.xml in Signer/Using/Configuration: Could we use bullets where we list
  the sort of things set in these files?  They're great guides for one's
  eyeballs, and help to quickly establish an overview of this rather
  complex set of facts.

  In-document references to other configfiles draw a bit more attention
  than they deserve; reading depth-first it made me stop to wonder if
  this is a link to bookmark or chase, which is distracting.

  Links to "here" show up in red, but they are not as useful as having
  the name of the configfile in red.  Our eyeballs quickly spot those
  links, and having meaningful text in red is useful for navigation.

  Reference to ".rng" is not directly meaningful to the reader; actually,
  it is the underlying semantics that cause syntactic constraints, so why
  not replace "Some syntactic constraints...should be made" with "Not all
  possible configuration texts are meaningful however." (and skip the
  paragraph break).

* Signer/Using/Configuration/conf: What does <!Privileges> mean?  (Twice)

* Signer/Using/Configuration/kasp: The reference to ISO 8601 could be
  usefully expanded with a reference to the writeup of what it means, as
  currently detailed in Signer/Using.  OTOH, since this refers to Wikipedia,
  one could wonder why there is a local copy of this information on our Wiki.
  Consistency in whether this is on our Wiki or on Wikipedia would be nice.

  What does <!Purge> mean?

  This file mentions ZSK for the first time.  A reference to documentation
  explaining what it is / why it is useful could be handy here.  Specifically
  because it is (principally) an implementation choice to use the ZSK/KSK
  distinction.  A quick note would suffice: "OpenDNSSEC follows the commonly
  advised approach of signing resource records with a short-lived
  Zone Signing Key (ZSK) and signing that with a Key Signing Key (KSK) which
  is longer and can therefore safely be used over longer periods of time.
  For details, see RFC 4641."
  Why add this here?  Because the reader I've had in mind is one who is
  aware of DNS, but not necessarily of DNSSEC -- it is precisely to avoid
  detailed knowledge of DNSSEC that OpenDNSSEC appeals to that reader.

* ods-control in Signer/Using/Commands:  I am missing "ods-control status"
  as a convenient check on the wellbeing of >1 daemons.  But that's a feature.

  "It can pipe commands" is implementation detail that is not helpful to
  the reader who wants to know how to operate ods-control.  Why are not
  all the following commands phrased in terms of ods-control instead of
  the various underlying utilities?  This'd be clearer to the new user.

  "You can also start/stop the daemons ods-enforcerd and ods-signerd.":
  I didn't find those on our RC1 install.  Instead, I found Engine.py
  and ods-enforcerd.  If daemons are named, it sounds like I can ps|grep
  for them.

* ods-ksmutil in Signer/Using/Commands: it is clearer if "zone delete" 
  is also layed out as code.

* Signer/Using/Commands in general: I would like to know why/what/how
  for each of the commands: why are they there (what does it accomplish
  in terms of getting your zones signed) and what is the approach (setup
  a zone list in the database, say) and how (the commands to run to get
  it done).

  Each of the commands would ideally link to the overview; what is its
  part in the signing flow of domains, what components does it play on
  and which responsibilities are fulfilled by it (and inhowfar)?

  After each command, it would be _very_ useful to have a way of checking
  up on the result, to ensure that it was successful.  This will greatly
  aid in both understanding and debugging.  Without this, all we can do is
  copy/paste examples and guess what they will do.

* Signer/Using/Running: Most remarks on Signer/Using/Commands apply here
  too:

   - Why is a step needed in the grand scheme of the domain-signing flow,
     what responsibilities are (partly) taken care of
   - What is the method followed (inserting zones in a database, kicking
     the signer to sign right away or scheduling for later, etc.)
   - How is it accomplished (with what command, and how can its result be
     checked manually)

* Signer/Using/Debugging: A missing page?

   - It does not work -- but how to trace the domain through the system
     and detect the spot where it goes wrong?
   - How does a system look when it is "operating within parameters"?
   - Where to look for errors -- which log facilities, which loglevels?
   - Where can one search and browse through experiences of other users?


This is a list of things, as requested during the meeting.  I did my best
to find anything that could possibly help the newcomer.  I don't mind
picking up on either or all of these, when so requested.  Just let me
know if I am raising valid questions to be answered in the documents; I
think there is room for improvement, even if what we have right now is
not bad at all.


Cheers,
 -Rick