BIND 10 #3006: Import datasource design documentation into BIND 10 git repo

[BIND 10 Development]

#3006: Import datasource design documentation into BIND 10 git repo
-------------------------------------+-------------------------------------
            Reporter:  muks          |                        Owner:  muks
                Type:  task          |                       Status:
            Priority:  medium        |  reviewing
           Component:                |                    Milestone:
  documentation                      |  Sprint-20130625
            Keywords:                |                   Resolution:
           Sensitive:  0             |                 CVSS Scoring:
         Sub-Project:  DNS           |              Defect Severity:  N/A
Estimated Difficulty:  0             |  Feature Depending on Ticket:
         Total Hours:  0             |          Add Hours to Ticket:  0
                                     |                    Internal?:  0
-------------------------------------+-------------------------------------
Changes (by vorner):

 * owner:  vorner => muks


Comment:

 Hello

 Replying to [comment:6 muks]:
 > This has been taken into account and dummy files are generated in this
 > case. We also use the `devel` make target now, just like in the
 > upper-level directories.
 >
 > The design documentation is not installed.

 Hmm. I think either one of these changes would suffice, but both is
 unexpected. I mean, if I want to compile the software, I usually don't
 require the development documentation, so it being skipped is OK and what
 I want. But if I actually ask to generate the development documentation
 explicitly, by `make devel`, then it should probably fail if it can't be
 fulfilled, not create dummy files.

 Also, it looks awkward to put text into a png image (and they don't show
 at all in the document, if asciidoc is installed and the plantuml isn't).
 What about placing a dummy png file there (containing the text as image)
 and copy it to the target one instead of echoing a text there?

 > > Is this generic make syntax, or GNU extension?
 > > {{{
 > > BUILT_SOURCES = \
 > >     $(UML_FILES:.txt=.png) \
 > >     $(TEXT_FILES:.txt=.html)
 > > }}}
 >
 > I am not sure. Maybe we should put this branch through the builders and
 > see what happens.

 That could work. I also think using `$(patsubst $(UML_FILES),%.txt,%.png)`
 should work (I believe that one is standard), I don't know about this.

 > > Are the diagram sources written by hand, or some tool helps with them?
 > > Writing the formatted text is easy, but these seem rather more
 > > complex.
 >
 > They have been written by hand.
 >
 > They are rather simple actually. It looks complicated because there are
 > so many instructions. But they are rather a set of sequential
 > instructions, just bulky. Personally, I prefer that we code it up
 > manually (so that the text is as readable as it can be) and not using a
 > visual tool, but I guess both ways is fine as long as it's maintainable.

 I don't know. I did write some postscript images for my thesis. But I find
 it easier to draw them often.

 Jinmei must have used something to make his, maybe we could just use that?
 And import his images as they are?

 > Replying to [comment:5 jreed]:
 > > The generated html docs look nice, but we need to use a single tool --
 > > we already decided on doxygen.
 >
 > We decided on using `asciidoc` during the team meeting call. There are
 > already several docs in the `docs/design/` sub-directory which use
 > `asciidoc` (and some more in branches that will be merged).
 >
 > However, I agree it is good to be consistent and use a single tool where
 > possible. But currently the Doxygen design documentation seems in bad
 > shape. We should first clean it up and make it straightforward to add
 > new content.  Using Doxygen is outside the scope of our initial
 > decisions to use `asciidoc` for this ticket which has already been
 > implemented, so let's create further tickets for this. The main goal of
 > this ticket was to get the documentation in the repo so it can be
 > maintained.

 I don't think we necessarily need to use the same tool. After all, these
 are two similar but different tasks. User documentation needs something
 else than developer documentation.

 With developer documentation, the formatting quality and such can be
 significantly lower. It doesn't have to impress. It is enough to be just
 readable. On the other hand, the developer documentation must be easily
 and fast editable, which docbook is far away from that. So it makes sense
 to me to use different tools for different kinds of documentation.

-- 
Ticket URL: <http://bind10.isc.org/ticket/3006#comment:7>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development