need feedback on new wiki organization

Hi folks,

I've moved all of the more straightforward content onto the new wiki--it still needs review and, of course, is open to rearrangement, etc. Linked here are some ideas about how to handle the rest of the wiki content (primarily specs and meeting notes). Please look it over and let me know what you think! Perhaps we can schedule a conference call next week?

Thanks,
kirsten

Hmmm, there are lots of decisions to be made here.  No single good answer. Some of these pages could be migrated to the new site and stored as technical documentation under specific teams (e.g. the Kepler Object Manager design document could be hosted by the Framework team).  However, some other pages are out of date (e.g., the Kepler Startup Time document is out date because we've already decided to modularize the system much more than proposed here, and the page is really more of a SEEK meeting report than a Kepler page).  I think we should avoid moving stuff that is no longer useful and clearly mark what is still useful but out of date as such.

Can we meet later this week to go over each of these pages?

As for standardizing the design documents, I'm not sure how useful this will be at this point.  We are developing a richer set of documents for our various teams and different groups may have different needs.  Maybe we could look for opportunities for standardization after the teams have posted a large number of new documents?

Thanks!

Thanks for taking a look at the document, Tim! I can talk pretty much any time on Thursday of this week, or on Friday anytime between 10 and 2. Would either of those days work for a conference call?

Thanks,

kirsten

Kirsten, either 10 or 11 am tomorrow (Friday, 19sep08) would be good a good time for me.

Ilkay, Matt, do you want to participate?

I'd really like to participate tomorrow, but I'm going to have to skip this one due to pressing deadlines (like a seminar to be prepared for tomorrow afternoon) that I've been putting off way too long.  So... a synopsis of your decisions would be great.  I looked at Kirsten's work so far and generally I am happy with it.  I'd like to see the Developer section have a sensible set of introductory pages that explain how to develop with Kepler, and a reference section that accurately explains how Kepler actually works form an architecture and design perspective.  These pages should reflect the current release, or maybe have different subsections for each major release.  Then I think the technical design and implementation details of particular new or changing subsystems should be contained within the correct development team collaboration area, and will become the responsibility of that team to keep updated.

In terms of the documents still to be migrated -- I'd like to make sure we don't lose any of that content. For example, the ObjectManager description has a lot of valuable reference information, even though its not quite correct.  I suggest these pages get migrated into 'Legacy' folders inside each of the appropriate team areas, which will allow the proper team to revise them to reflect current behavior and then migrate them to the proper team or reference part of the site.  They could even be made private to the team for the time being if they are misleading or otherwise contain material we don't want broadly distributed to avoid confusing things, etc.

Looking forward to hearing how you decide to move forward.

Hi-

Tim and I talked over the outstanding wiki issues and have some proposals (and questions), detailed below for comment:

1. Move the pages from the old wiki to the new. All pages will go into an "archive" folder beneath the appropriate team or group, with new incubation teams created when necessary (e.g., for user interface and Kepler Execution Monitoring documents). In addition to the archive folder, create a "work in progress" directory for current work and begin to use the "technical documentation" directory for completed work. These items will be listed as the last three items on the team/group homepage in the following order: 1. work in progress 2. technical documentation 3. archive. Team members can move archive pages if the destination chosen is not quite right, or promote an archived document to current (or just mine the archived doc for useful bits to repurpose/leaving the archived version where it is).

2. Implement a standard header on each specification page including a title, an overview of the page content and intended audience (if not all kepler developers), and the status.

3. Create an "Exemplar Approach" template in the Developer/Reference section that developers can use as a guide when creating new specifications. Question: Are there any existing specifications that would be good examples?

4. Invert the nav items in the Developer section so that documents relevant to all developers (get code, reference, faq, etc) are at the top and the more project-specific items are at the bottom. Propose that the nav menu be limited to three levels of hierarchy, and that the horizontal indent between levels be increased to more clearly indicate the hierarchy.

5. Add index pages to Teams and Groups directories providing more context about what each is, what resources are found there, and how to get involved. Descriptive content drawn from management charter.

6. Move the meeting notes to a new "Developer Meeting" directory under Developer. This directory will not appear in the navigation.

That's it! Please let me know your thoughts.

Thanks,

kirsten

That all sounds great to me.  I think limiting the menu to a fixed number of levels would be good, and I also like rearranging the order of things in the developers tree, and the use of the Archive folder.  I also support the standardized format for specifications, although as we don't have any formatting police we'll have to see how well that is adopted -- its good to try though.

Hi and thanks for the feedback! I've moved the documents we discussed to the new wiki. Aaron posted in the Framework forum that he did not think we needed a "work in progress" and "technical documents" directory/icon/distinction, and so I decided not to update all the team home pages with anything more than the Archive folder, at least not without further discussion. I moved images over to the new site unless they were linked from cvs (as was the case for many of the GUI pages). Not sure what (if anything) is going on with those cvs links, so I wanted to check in about whether they were okay to leave.  I also added a red status icon to the top of archived pages to indicate that the content was dated. Aaron also suggested that these icons be added with a style, or as part of the specification template--though perhaps that would be less important if we only indicate the status of out-of-date pages. Wanted to see if you had additional thoughts on the matter? Thanks!

The CVS links need to be repointed to the SVN server, especially as the documents have now moved.   This may be a fair amount of work as I think Laura had a lot of links to files in CVS, especially images in her GUI mockups.

Hi Kirsten,

I missed this phone call. Do you think we can have a phone call  Monday afternoon or later next week?

I like the suggestions and have a few additions.

Thank you!
-ilkay

Previously Kirsten Menger-Anderson wrote:

Hi-

Tim and I talked over the outstanding wiki issues and have some proposals (and questions), detailed below for comment:

1. Move the pages from the old wiki to the new. All pages will go into an "archive" folder beneath the appropriate team or group, with new incubation teams created when necessary (e.g., for user interface and Kepler Execution Monitoring documents). In addition to the archive folder, create a "work in progress" directory for current work and begin to use the "technical documentation" directory for completed work. These items will be listed as the last three items on the team/group homepage in the following order: 1. work in progress 2. technical documentation 3. archive. Team members can move archive pages if the destination chosen is not quite right, or promote an archived document to current (or just mine the archived doc for useful bits to repurpose/leaving the archived version where it is).

2. Implement a standard header on each specification page including a title, an overview of the page content and intended audience (if not all kepler developers), and the status.

3. Create an "Exemplar Approach" template in the Developer/Reference section that developers can use as a guide when creating new specifications. Question: Are there any existing specifications that would be good examples?

4. Invert the nav items in the Developer section so that documents relevant to all developers (get code, reference, faq, etc) are at the top and the more project-specific items are at the bottom. Propose that the nav menu be limited to three levels of hierarchy, and that the horizontal indent between levels be increased to more clearly indicate the hierarchy.

5. Add index pages to Teams and Groups directories providing more context about what each is, what resources are found there, and how to get involved. Descriptive content drawn from management charter.

6. Move the meeting notes to a new "Developer Meeting" directory under Developer. This directory will not appear in the navigation.

That's it! Please let me know your thoughts.

Thanks,

kirsten

Hi Ilkay-

I could talk anytime between 2 and 4 on Monday afternoon if that works. Or on Tuesday morning if that is better for you. Please let me know what works best.

thanks!

kirsten

Indeed, there are a number of links in the UI pages Laura created. I'm pretty sure I can change them all before tuesday though.

thanks,

kirsten

Previously Matthew Jones wrote:

The CVS links need to be repointed to the SVN server, especially as the documents have now moved.   This may be a fair amount of work as I think Laura had a lot of links to files in CVS, especially images in her GUI mockups.