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.
>
> 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.
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 :)
> 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
- what goes into an "everybody can write" wiki
- what goes as into a doxia generated site.
So, maybe best to lay this all out as a proposal?
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?
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
