[Opendnssec-develop] Ideas for improving documentation

Thu Dec 17 10:44:21 UTC 2009

The points listed below would be a great addition. I would really
welcome it as inexperienced user.

I'm afraid it might cost much time to manage/moderate but in the future
a forum with separate parts for several distributions would be really
helpful. That way you will create an interactive and more responsive FAQ
tailored towards the distributions. Instead of thinking about what the
user wants to know, you give users a chance to exchange experiences. The
mailing list hasn't got this more permanent and inter-exchangeable
characteristic.

Is there anything planned for this in the near future?

Cheers,
Rick

-----Original Message-----
From: opendnssec-develop-bounces at lists.opendnssec.org
[mailto:opendnssec-develop-bounces at lists.opendnssec.org] On Behalf Of
Matthijs Mekking
Sent: donderdag 17 december 2009 10:28
To: Rick van Rein
Cc: opendnssec-develop at lists.opendnssec.org
Subject: Re: [Opendnssec-develop] Ideas for improving documentation

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