+1 this is a fantastic idea.. would it take the form of an elaboration on the mvn site plugin?
I propose that, at the lowest level, a test asserting that javadoc containing more than the default @author and @return tags in the javadoc for methods that arent property accessor/mutators would ensure most code is documented. then, if the test is met, the javadocs can be considered 'present'. Naturally there are any number of other tests... This would be the easiest level of compliance with the edict ( all code must be documented). Naturally, the site generated for the artifact woud provide the higher level overivew of the code thats much needed when diving into something... I propose perhaps a new type of doc format could be created / employed by the site plugin. src/site/wiki, or somehting like that. this would be content that once processed by the plugin would be entered into a known wikis (configurable in the pom) database which itself is editable/annotatable.. somehow the docs might be synced with this wiki.. or something... This would allow the structure of the wiki/documentation to spring forth from the code and the developers where the knowledge is cached. it would also allow coupling/interaction between the javadocs/reports and the documentation. But once that basic structure is set up, it would easily migrate to an interactive community driven format. the wiki would facilitate comments. the plugin might even read the wiki db and restore the comments into the documentation or something... These are all just proposals, as I wonder what this sort of solution might look like. Josh On 11/3/06, [EMAIL PROTECTED] < [EMAIL PROTECTED]> wrote:
+1 This would make it even possible to create a user/project dedicated manuals. The project pom-file already has all plugins being used by the project. The generated manual will then just include the docs for these plugins and use the actual plugin version. Regards, Minto -----Oorspronkelijk bericht----- Van: Gisbert Amm [mailto:[EMAIL PROTECTED] Verzonden: vrijdag 3 november 2006 9:43 Aan: Maven Users List Onderwerp: Re: Maven rant Why not use the central repo for documentation aswell? E.g. in http://www.ibiblio.org/maven2/plugins/org/apache/maven/plugins/maven-ant-plugin/2.0-alpha-2/ could exist a bundle named user-manual.zip, containing the sources for the user-manual. There could be a reference-manual.zip, a developers-manual.zip and so on. The Wiki pages could be generated out of these sources. One step of the release process of a plugin (or the Maven core) would be to integrate possible user comments from the wiki into the documentation sources and regenerate the respective wiki pages. A Maven plugin could be written to download all document sources of a certain category, bring them into a reasonable order (defined by models within the plugin), add introductionary material from common bundles, table of contents, indexes etc. and produce a users manual, reference manual and so on in a format the user can choose (HTML, PDF ...) Even the Maven website could be produced by such a plugin; it would just be defined by another documentation model. Just applying the same principles used for software production to documentation ... I hope I was able to make myself understood (sorry for my English) and am not dreaming too far into the blue ... -Gisbert Gregory Kick wrote: > Ok, this is think outside the box time... I like Thomas' comments on > centralizing documentation. I really, really like Thomas' comments on > centralizing documentation. However, I think the logistics may be > off. I'm thinking of the documentation problem as similar to the > build problem. > > Before there was maven, users had to go from site to site downloading > jars and collecting them into a useful, coherent code base every time > they wanted to build because a bunch of different groups contributed a > bunch of small, but useful artifacts. That got fixed. Unfortunately, > we're now finding that users are going from site to site browsing > documentation and collecting it into a useful, coherent knowledge base > every time they want to understand something because a bunch of > different groups contributed a bunch of small, but useful bits of > documentation. > > So, here's what I propose: Lets create a repository for > documentation. The docs will exist within the projects, as they do > now, and we'll use an APT/Wiki hybrid that allows for linking between > projects (e.g. [[groupId:artifactID]]) and documents (e.g. guides, > javadocs, etc.) within those projects. That way, there's quality > control because the docs have to be committed, we avoid the > unrealistic > make-a-giant-book-that-somebody's-going-to-be-in-charge-of-because-I-d > on't-want-to > > plan, and we get the centralized feel with out having to duplicate the > little bits of usefulness that already exist. > > Obviously, there will be a lot of gaps, broken links, etc. in the > early stages, but I don't think that it would be any worse than with a > typical wiki. There may be a slower turnaround in updates, but that > might be balanced out by the fact that current documentation could be > reused. Later, if we want something more interactive there could be a > tool for generating and submitting documentation patches via this > online repository. > > So that's my little bit of brainstorming. There are obvious issues > like hosting, but for now I dare to dream... :-) Thoughts? > > On 11/2/06, Thomas Van de Velde <[EMAIL PROTECTED]> wrote: > >> The problem, as I see it, is that the documentation is fragmented. >> Unlike >> Hibernate and Spring, which provide a single reference manual which >> is kept up to date with every release, Maven documentation is spread >> all over the place (wiki, generated sites, better builds with Maven, >> etc.). The problem gets worse with the isolated documentation for >> plugins. Plugins may make sense from a technical point of view, but >> an end-user can care less about plugin seperation from the core. >> They want to see consistent documentation for all features, whether >> those are provided by the core or by plugins. By forcing ALL >> documentation to be centralized (e.g. in a reference manual), you >> naturally get better consistency and logical flow between the >> different pieces (Instead of a bunch of isolated how-to's and plugin >> pages). >> What a >> mess Spring's documentation would be if they'd start generating >> seperate web sites for each framework they integrate with! >> >> Users have been complaining for years about Maven documentation and I >> agree with those who say that this is a break on wider Maven >> adoption. As an experienced user, I have no trouble finding what I >> am looking for but I can tell you from my experience dealing with >> many new users, that the newbies have big trouble finding their way >> through the documentation jungle. More than once have I seen >> projects giving up just because they didn't find an easy way to get >> started. This is highly regrettable as they are missing out on a >> great tool! >> >> So my recommendation would be: >> >> 1) Centralize documentation (prefereably on a wiki so that users can >> comment on questions). Why not take the Merger book as a starting >> point? >> 2) Update documentation with every release. >> >> An undocumented feature is an unexisting feature. >> >> Thomas >> >> On 11/2/06, Adam Hardy <[EMAIL PROTECTED]> wrote: >> > >> > Wendy Smoak on 02/11/06 22:34, wrote: >> > > On 11/2/06, Sebastien Brunot <[EMAIL PROTECTED]> wrote: >> > > >> > >> What I meant by "it" was the comment mechanism. >> > > >> > > Right... it doesn't exist yet, we need to design it. >> > >> > The comment mechanism can be a wiki where the public can only add >> > at >> the >> > bottom >> > of the page, and the contributors are the ones who sort out the >> wheat from >> > the >> > chaff occasionally to enhance each page from its comments. >> > >> > > Earlier, I asked, "Any ideas on how to present that as an option? >> > >> > It's done at mysql[1], php and someone said Hibernate and I think >> Drupal. >> > But my >> > quick investigation there didn't show anything. Check out mysql though. >> > Perhaps >> > their documentation publishing framework is OS. >> > >> > > What would the menu link be called? How should the pages on the >> > > wiki be organized?" >> > >> > I think the whole maven documentation website should be >> wiki-commentated >> > (is >> > that the correct verb here??) >> > >> > So each plugin remains as it is except the wiki-commentary can be >> appended >> > to >> > the bottom of every page. >> > >> > I think that any plugin that makes it onto repo.maven.org should >> > get >> its >> > docs >> > site on the website too, at least for the releases. >> > >> > regards >> > Adam >> > >> > [1] http://dev.mysql.com/doc/refman/5.0/en/linux-rpm.html >> > >> > ------------------------------------------------------------------- >> > -- To unsubscribe, e-mail: [EMAIL PROTECTED] >> > For additional commands, e-mail: [EMAIL PROTECTED] >> > >> > >> >> > > -- Gisbert Amm Softwareentwickler Infrastruktur WEB.DE GmbH Brauerstraße 48 · D-76135 Karlsruhe Tel. +49-721-91374-4224 · Fax +49-721-91374-2740 [EMAIL PROTECTED] · http://www.web.de/ --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] DISCLAIMER De informatie in deze e-mail is vertrouwelijk en uitsluitend bestemd voor de geadresseerde. Indien u niet de geadresseerde bent, wordt u er hierbij op gewezen, dat u geen recht heeft kennis te nemen van de rest van deze e-mail, deze te gebruiken, te kopiëren of te verstrekken aan andere personen dan de geadresseerde. Indien u deze e-mail abusievelijk hebt ontvangen, brengt u dan alstublieft de afzender op de hoogte, waarbij u bij deze gevraagd wordt het originele bericht te vernietigen. Politie Amsterdam-Amstelland is niet verantwoordelijk voor de inhoud van deze e-mail en wijst iedere aansprakelijkheid af voor en/of in verband met alle gevolgen en/of schade van een onjuiste of onvolledige verzending ervan. Tenzij uitdrukkelijk het tegendeel blijkt, kunnen aan dit bericht geen rechten worden ontleend. Het gebruik van Internet e-mail brengt zekere risicos met zich. Daarom wordt iedere aansprakelijkheid voor het gebruik van dit medium door de Politie Amsterdam-Amstelland van de hand gewezen. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
