Musachy Barroso wrote:
About the snippets, they are handy for commiters because they can
update the code and forget about the wiki, but yes, it prevents users
with just a CLA to fix problems. For these quick spelling/minor
comment changes you can ping me in IRC and I could fix them right
away.
That's the other half of the point I'm trying to make. Forget about the
high barrier for contributing to the docs but focus on the idea that a
committer can update the code and forget about the wiki. By making the
content of the documentation external to the documentation it causes
several problems.
1) It's easy to get confused over which content is in the documentation.
https://issues.apache.org/struts/browse/WW-2652 &
http://developer.atlassian.com/jira/browse/SNIP-11
2) Code committers can break the docs and they have no way of knowing.
http://developer.atlassian.com/jira/browse/SNIP-10
3) Code commiters can change the content of the documentation without
any idea of the context in which their changes will affect the
documentation. http://developer.atlassian.com/jira/browse/SNIP-12
I understand why the idea of single sourcing the documentation is
attractive. Mainly that there are no docs to write because the code is
the documentation. But with the snippet macro the result is
documentation that is hard to update and impossible to maintain with any
degree of quality.
The theory behind the snippet macro is to implement the ideas for
LiterateProgramming (http://c2.com/cgi/wiki?LiterateProgramming). Which
states: "Note that documentation means a description of the
implementation, /not/ a user manual.". Javadoc already does this!
Real single sourcing would be using docbook to generate a website and a
pdf, not what is being done with the snippet macro.
From the point of view of someone functioning in the role of a
documentation maintainer what would the benefit of the snippet macro be?
-Matthieu Chase Heimer
