[Opendnssec-develop] Ideas for improving documentation

Thu Dec 17 09:27:38 UTC 2009

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

In addition,

* The documentation should really go onto the website, instead of the
wiki. As it turns out, people get confused when going from website to
wiki and back again.

* (more website stuff) The home page does not provide enough information
for users why they should use OpenDNSSEC. Perhaps add a new header 'Why
OpenDNSSEC' with pointers to About and Features.

* The documentation on the wiki appears to be not usable by users:
  - libopenssl-ruby seems not to be a requirement (at least not for
./configure)
  - is libsqlite3 needed?

* The accompanying guide is only useful for Ubuntu users.

* There is a installation TODO for mysql.

Best regards,

Matthijs

Rick van Rein wrote:
> 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
> _______________________________________________
> Opendnssec-develop mailing list
> Opendnssec-develop at lists.opendnssec.org
> https://lists.opendnssec.org/mailman/listinfo/opendnssec-develop

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iQEcBAEBAgAGBQJLKfmIAAoJEA8yVCPsQCW5YscIALdoxn8aJz2upILXAV43gNRh
qywKmQVVFukt7KjFWGxXWsPTc8/+PelB84y0QJjF8uRPy3gH208m5TZvfiRcN43o
BMFwQhkP13t9jNFstynC0QQBHfF43s9y+aChIcmSIIMOWXVQzoyCv55Rlor4b3l8
tDWZoMaRxOP7JhGjARvky7QiT4FEJzWM0xgtL2Qs5WuxKtuRpGPnP+iICPp56WIl
IPLfurVYciyMi68jEmiHTWAOJlq9vGLm9uukFHJL6sTwGcWWgfRnIpItdyFewICL
X52VXdEcdbJWwXsUM6QkEkB0CtAA1OMiGl/d//0VGblYrdGpRnZpoMFDHauflsU=
=ZA5x
-----END PGP SIGNATURE-----