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:
                Type:  task          |  vorner
            Priority:  medium        |                       Status:
           Component:                |  reviewing
  documentation                      |                    Milestone:
            Keywords:                |  Sprint-20130625
           Sensitive:  0             |                   Resolution:
         Sub-Project:  DNS           |                 CVSS Scoring:
Estimated Difficulty:  0             |              Defect Severity:  N/A
         Total Hours:  0             |  Feature Depending on Ticket:
                                     |          Add Hours to Ticket:  0
                                     |                    Internal?:  0
-------------------------------------+-------------------------------------
Changes (by muks):

 * owner:  muks => vorner


Comment:

 Hi Michal

 Replying to [comment:4 vorner]:
 > Hello
 >
 > I agree that the class diagram might need some improvements. For one,
 > the original one had layers (which seemed very useful) that are lost
 > in this one.

 True. There are other conversion tools such as `umlgraph`. Maybe we can
 investigate them. For now, I guess something is better than no class
 diagram.

 >
 > Distcheck fails, with:
 > {{{
 > make[5]: *** No rule to make target `overview.png', needed by `all'.
 Stop.
 > make[5]: Entering directory
 `/tmp/bind10/bind10-2/bind10-20130529/_build/doc/design/datasrc'
 > }}}
 >
 > I think we don't want to require these tools on normal user's system
 > to compile the sources. If one of the tools is not ready, it will
 > reject compilation. We don't compile man pages if docbook is not
 > available, I think the same approach would be reasonable for developer
 > documentation. Especially with the `plantuml`, which is not available
 > as package for gentoo (and I see reasons why their ebuild they provide
 > on the wiki page was not accepted).

 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.

 > What is `a2x`? Why is it mentioned in both rules in the makefile?

 `a2x` is a tool that comes with `asciidoc`. I had initially used this to
 generate the HTML output (as it generates a more plain looking HTML),
 but standard `asciidoc` looked better and that was picked in the end.

 > 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.

 > 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 didn't read the text thoroughly, but I guess it is the same one as
 > from Jinmei.

 Nod.


 Hi Jeremy

 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.

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