comments inline. Cheers,
john
1) should we drop the standard reports from the maven site?
I never was really pushing to drop reports altogether; it just didn't really make sense to me to have them on the main site, in addition to the individual reference pages. IMO, until we can aggregate all of those reports for the entirety of Maven, it's confusing what they represent. Also, it clutters up the main site for users who might not have any use for that information.
> 2) JIRA & documentation > > Can anyone explain what the documentation version is for?
The documentation version in JIRA was my feeble attempt to find another grouping for documentation-related issues. At the time, I didn't know issues could have more than one component association, and I wanted to get a handle on how documentation was coming without destroying the association of what it was trying to document.
What do others think about merging the documentation categories for now, > since we seem to agree this isn't the right breakdown of docs? (I saw a > couple of dupes when I surfed across categories, but none within a > single one). This gives a more managable task list.
+1.
3) What is the role of the wiki? > > Wendy made some very good points about the accessibility of the wiki for > getting doc contributions, which I think is worth exploring, especially > since we can automatically bring it into the site.
I think the wiki is the best candidate for making some of the conversations taking place on the users list and IRC more permanent. It's a fast way for users to start helping users, without people like me serving as a bottleneck. As for quality, I think that can also be driven by the user community to some extent, and shepherded by us.
> However, it comes with the downside that it can be less thoroughly > reviewed and sometimes unstructured unless the person is really putting > some extra effort in.
I would expect that a certain amount of social pressure would eventually drive the wiki documentation to become and stay fairly accurate, if not in alignment with "best practices". As for formatting, I'd love to see some sort of way we could offer a template for framing an example...something that would make one document look a bit like the others, to make it easier to pull out information. Standards will be hard to enforce, unless there is a clear benefit to the community, IMO. But something like the loose organization on the different pages linked from http://www.linux-laptop.netshould be good enough...
> > So I think we have some alternatives: > - use the wiki for everything, auto generate site
Do you mean that we'd keep all of our static site documentation on there as well, and render everything from confluence markup? This seems a bit drastic.
- use the wiki for a specified section of the site, autogenerate (and > perhaps mark as being contributed) - use the wiki as a holding area for new doc contributions
I'm not sure I understand. Why bother rendering any of the wiki content as static pages? This will only slow down user contributions in terms of revisions to existing docs, which will in some ways compromise their quality. I'd prefer to see a combination of static site pages and wiki, where the static site might refer to a corresponding wiki section for any given discussion. So, the assembly plugin might have the bare-minimum "official" docs, which include basic usage, the plugin report, etc. and a _link_ to the wiki area for the assembly plugin. In this area of the wiki, users can add their own examples, workarounds, etc. The only drawbacks I can see here are in keeping the wiki information up to date with new releases, and navigational consistency between wiki and the main site. I really don't see much value in rendering the wiki content to static pages, particularly when we'll have to implement in Doxia the confluence macro-set we'll need to represent a technical discussion...things like the code macro.
> I'd go with a combo of the last 2. I think the cookbooks section should > have 2 parts - an apt/etc part and a contributed part autogenerated from > the wiki using Wendy's proposal (and possibly doing the same per plugin) > > I'm in favour of using APT/local confluence markup for the main, > verified part of the site (would want an easy way to convert confluence > to APT, though). > > Thoughts on these? I support the idea of a lot of the content being developed on the wiki and slurped into the main site simply. But this is mildly difficult since we do not want to lock all that process into confluence by any means...so what if we were to have a custom template or something in confluence and mapped a defined page x -> site x content mapping, and in that custom template or whatever try and validate that the content saved to the page adhered to a trimmed down set of tags that were simular to apt, or at least we spit out errors and failed the site generation in continuum if the pulling of text over from the confluence didn't match a set of info... basically anything that made the site really easy to make sure that anyone who was working with it followed strict guildlines format wise. would be really nice if we could pull a particular part of a wiki page into the site and then surrounding that there could be comments and whatnot and calls for improvement or what...say if the confluence page of 'Welcome Page' had a table in it with and id of "content" and in that table was the actual test for the page, and below that brett could add something along the lines of 'todo: spruce up the welcome text so that people know the difference between maven 1.x and latest release of maven. would be cooler still if there where multple tables (or whatever) with ids for content in different translations and we could manage that site content in different language through the same mechanism, all on the same page...and an aggregating page that shows pages of text that were missing translations for a particular language. being able to manage language translations through the wiki would make it easier for people to contribute along those lines then working with properties files and svn/patchs. though if you take into account language translations and whatnot then having the majority if not all of the website in the wiki starts making more sense, perhaps even going so far as to say the plugins could seed the wiki documentation effort automatically for english and then translations based on that being pulled down for website generation....depends on how fully you want to support internationalization. jesse -- jesse mcconnell jesseDOTmcconnellATgmailDOTcom --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
