[bind10-dev] Documentation - inplace vs wiki

[Michal 'vorner' Vaner]

Hello

I'd like to bring this question up, either now or we could talk about it at the
f2f, if there's some time.

We put some of the design documentation (I'm not talking about the API
documentation here, but about the more high-level one, like design choices,
graphs about how the components cooperate.) on wiki. It has easy markup, allows
including images, has hyperlinks, is easy to browse for anyone and so on.

But it has one major disadvantage. We have our code in svn, we will have it in
git. But the point there is that we have multiple versions of it, some of them
are parallel branches, some is just historical. But the versions may do stuff in
different ways, so the documentation, even if it was in the theoretical optimal
state where it fully corresponds to trunk, is wrong for the other branches.

So what I want to propose is to put our documentation into the svn/git as well,
together with the code. One example could be having a 'docs/' directory in each
component/library, just like tests. Then it could contain some document, for
example in doxygen markup, so we could generate the whole documentation. The
auto-generated documentation for trunk could still be linked on the pages.

What do you think? Does it make sense? Do we want to talk this over on the F2F?

Thanks

Have a nice day

-- 
Java: Write once, run everywhere
Perl: Write once, run away
Perl6: Don't write, it DWYW

Michal 'vorner' Vaner
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <https://lists.isc.org/pipermail/bind10-dev/attachments/20101213/840afc1e/attachment.bin>