[zeromq-dev] Documentation Proposal

[Martin Lucina]

Hi Peter,

having read through this thread I have the following comments:

1) Re. developer documentation generated from the source with Doxygen: I
have no real opinion on this, other than to concur with others comments
that to be useful it must be generated automatically from the current Git
master, and that the Doxygen documentation is targeted at 0MQ developers
and contributors rather than end users. I don't think that the Doxygen
documentation needs to be included with released tarballs of 0MQ.

2) Re. the state of the Wiki documentation; it would be useful if someone
went through the Wiki and either prominently marked as deprecated or
(better) just removed all the old 0MQ/1.x documentation. This has been the
source of some confusion from people, especially with people finding old
1.x documentation via search engines.

3) Re. the reference documentation in Git. I don't see any reason to change
anything here; the documentation is in a easy to write format with a
powerful toolchain and is separate from the Wiki for the reason that it is
essential material which must be packaged with the released product.

I would like to invite more people to contribute to the reference
documentation in Git; patches are welcome. Also, when someone writes
quality introductory material suitable for a tutorial this could be
included as a zmqtutorial(7) document, similar to how the Git people do it
with gittutorial(7).

-mato