On 22 May 07, at 10:37 PM 22 May 07, Brett Porter wrote:
Thanks for starting this - I downloaded the spaces while I was
offline and starting thinking about ways to do it also.
On 23/05/2007, at 8:28 AM, Jason van Zyl wrote:
Hi,
I started trying to reference artifact pages in the spec I've
written up for the artifact resolution and I found it impossible
to really find anything so I took John's initial outline for the
taxonomy that makes up our subject matter and I made an attempt to
align the wiki with the categories we have in JIRA.
I found the taxonomy page a bit confusing just looking at it. Which
are the classifications, just the top level headings? Can you post
the taxonomy to the list for discussion so we can go through it?
The wiki sucks as a commenting mechanism.
They are meant to align with the components in JIRA. But they are
disjoint and they have varied so long not much will make sense
without a few days work. I added some content to the taxonomy page
clarifying its use in that it's not a likely form you want to present
to users but a mechanism to categorize the content.
The components here:
http://jira.codehaus.org/browse/mng
Should mesh with:
http://docs.codehaus.org/display/MAVEN/Maven+Taxonomy
I'm going to sync them up a bit more and seeing as no one has looked
at this at all for quite some time I'll take a go at it.
I went through every document and put it on the front page. I put
our organizational stuff like design, dev processes, and doco
guidelines at the top and then put the taxonomy after that.
I think it's important that we have a clearly defined structure so
that it can be held to that over time. Personally, I prefer managed
hierarchy vs linking everything from the front page. I find it hard
to find things on there, and it'll rapidly get out of date.
That's what the taxonomy is supposed to be: a hierarchy. But given
that documents were lost in the wiki I put them all on that page so
that I could see them all and try to organize and cull them. Whatever
I saw I quickly tried to categorize. Again this is not the final form
nor is it what's useful by people trying to learn about Maven.
Essentially it should be a hierarchical outline which I'm modeling in
omni outliner. But for the time being as I find bits and pieces I'm
just sticking them on that front page so I can see them. The
hierarchy doesn't exist yet and that's exactly what I'm trying to make.
How about breaking this down by category first (processes, design
documents, etc), then applying the taxonomy to each under those? We
don't really need links to Jesse and John's IRC discussion on the
front page :)
Our processes are separate from the taxonomy. The taxonomy is just a
hierarchical grouping of information. I just put our process
documents I put there so I could see them. The design documents would
be one of the first derivative documents that link to the taxonomy.
Talking about artifact resolution would link to the "artifacts and
repositories" portion of the taxonomy.
I'm also going to try and collapse any separate documents that
belong together and take another pass at aligning JIRA components
with items in the taxonomy. Hopefully this will help us in the up
coming discussions about design. Ideally the site, the wiki and
JIRA should all mesh with the taxonomy. Not sure exactly what the
final form will be but I think this is a step in the right direction.
I agree consistency is good - I'd like to see the design documents
kept up to date and incorporated as content for developers to read
through to understand a component (and the user-ish portion of the
content turned into a proper user guide). I think this is what you
aluded to in your other mail.
I think we need to start making a call about:
- what content goes in the wiki
In progress documentation. We let stuff sit to long in the wiki and
now we have duplication.
- what goes into an "everybody can write" wiki
In progress documentation by people with no access to the official wiki.
- what goes as into a doxia generated site.
What we consider final designs and documentation.
Ad hoc, or in progress collects in the official space with devs
incorporating user space material as deemed fit. As the in progress
documents complete they should get moved/exported to a static site.
Whatever means we decide on.
So, maybe best to lay this all out as a proposal?
This is a separate issue. First I would like to deal with the
taxonomy and movement of information from the wikis to the static
site. How the site is actually organized is a process of making views
from the taxonomy.
So how about you work on the site proposal portion and I'll finish
the taxonomy organization. The organization of views versus the
organization of the information from which the views are made. My
focus here is removing the crap from the official wiki and organizing
it for the purpose of working on 2.1 coherently. Organizing the
entire structure of the site is beyond the scope of my modest effort
here.
I think a good chunk of this is done, and if you want to organize the
site according to what you see working I'm fine chiming in as things
form. I'm really not interested in discussing this for the Nth time
with no real results. Organize it according to what you have below
and we'll try it. That's a fine approach as far as I'm concerned. I
don't think anyone is going to argue if you're trying to organize the
site and make all the sites standard. That all looks good to me below
so now what's your next thought on actually having that be what we
have for each sub-project?
Let's run with that below, now what do we do to organize the actual
information for each sub-project and what tools can we make to make
the site making follow that structure below.
For each subproject, we should:
1) create an 'unversioned' site that contains:
- front page explanation
- download pages
- news, etc.
- links to related things
- link to documentation for both latest SVN and latest release
- stored in /site/ alongside /trunk/ in SVN (separate from the
main tree)
2) versioned documentation (publish each release, as well as latest
SVN to site)
- full subsite under the subproject site
- includes documentation for users
- includes javadoc, source cross reference
- bundled with distribution
- still annotate when things were added since sometimes people
will read documentation for a different version anyway
- stored under /trunk/ of the subproject in SVN.
3) developer documentation (always publish latest)
- other reports
- documentation for developers, architecture, etc.
- generate from /trunk/ of the SVN
- design proposals written in the wiki and published to the site
- project process / plans documentation written in the wiki and
published to site
4) contribution area
- authored in wiki, generated to static files, linked from site
(http://maven.apache.org/scm/wiki/scm-matrix.html)
- FAQ, cookbooks
- always up to date
- not distributed with binary
- may be converted into versioned documentation for a future
release if useful
So we end up with, for each subproject:
- a contribution wiki space (knowledgebase/cookbook/etc)
- a project management wiki space (roadmap, design documents, etc)
- a versioned user documentation site in /trunk/ of SVN
- an 'unversioned' presentation site that represents the top level
and ties all the above together in /site/ of SVN
Thoughts?
Go for it.
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
Thanks,
Jason
----------------------------------------------------------
Jason van Zyl
Founder and PMC Chair, Apache Maven
jason at sonatype dot com
----------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
