home contents changes options help subscribe

last edited 8 years ago by klm

WikiForNow - Wiki adjustments to increase near-term comfort in the fishbowl

Owner: KenManheimer

Created: 11/03/2000, Revised: 11/11/2000

Status: The project that grew from this proposal is done - see http://dev.zope.org/Wikis/DevSite/Projects/WikiForNow for details.

Problem

While wikis as they stand provide benefits for the fishbowl process, we've all been chafing under some shortcomings, some of which need to be rectified soon, to reduce chafing and increase scalability of the process to increasing numbers of items (proposals and projects):

  • Document authors and community members alike have difficulty tracking feedback about the document, both in learning that some change has been made and in sorting out the gist of the changes.

    People who give feedback can get discouraged when they have no sign that the page authors are paying any attention to their feedback, which can undermine the feedback process.

  • As implemented in the version on zope.org, there are some glitches in the rendering of the wiki text, in particular, sometimes surprising and/or unfavorable inference of wiki references and general StructuredText?. This can defeat the ease of use and low impedance that wiki and structure text should offer.
  • Control over who can comment and who can edit items is very rudimentary - meaning that we've been depending on the kindness of strangers for the integrity of our documents, and for attribution of changes, etc.
  • Similarly, we've been depending on authors to employ proposal and project structuring conventions, with mixed success.
  • It is too hard to tell the status of a document - distinguish languishing documents from thriving ones.

Proposed Solutions

(For each of item i've assigned effort and value ratings, from 1 to 5, with 5 highest in each rating type. As an experiment, we're inferring bang-for-the-buck as Value/Effort, and tackling the items inorder, higher bang-for-the-buck items sooner. Interesting. If you have urgent feelings about changes to the estimates, let me know.)

  • last-modified prominence:

    Make the page's last-modified stamps more prominent, indicate the member that did the modification, and provide some definite status indicators in the default formats.

    Effort: 1, Value: 3, Bang-for-the-buck: 3, Time: 2 hours

    Result: (1 hour)

    • Using simon's idea for joining entire-wiki and current-node contents into a single link above the title bar, which leaves room for the date and last_editor, which is now being recorded.
  • Text formatting instructions:

    Improve the text formatting instructions, and make a link to them more prominently available from the edit page, so people don't feel like they have to experiment to come up with the right text formatting.

    (Emphasize that using code - and pre - will (due to fix, below) mean that people can use of code notation around text describing CamelCase function text, etc.)

    E: 1, V: 3, B: 3, T: 2 hrs

    Result: Draft version at WFNTextFormattingRules - feedback welcome! Either on the page, or in a comment box it links.

  • Comment mechanism:

    Implement a very simple comment mechanism, using a form which appends the comments to the end of a document. (The submitter's name and id, the date, etc should be automatically included.) This comment mechanism will be built into a derivative of the wiki page, and turned on if the visitor has "commenting" privilege for the page.

    The comments should have slots for the document owner(s) to indicate that they've read the item and responded, to make it easier to account for responses or their lack.

    The option to add comments will be controlled by the visitor having a role specified by the page owner - see below.

    E: 2, V: 5, B: 2.5, T: 4 hrs

  • Page creation flow:

    Change the page creation flow so that new pages are created only after the choice to edit the page is made, as opposed to immediately when the question mark is clicked. (It may be that the new version of ZWiki? provides for this - we have to take a look at the new version, in any case.)

    E: 2, V: 5, B: 3 (~factoring in template and page-types tasks), T: 4 hrs

    The page templates and alternate page-type tasks both depend on this, so it has to be done before they are, hence we take a bang-for-the-buck that's the maximum of the others.

  • New-page templates:

    Enable identification of a template for initial content of new pages, making it easy to unambiguously convey the structuring and formatting conventions.

    E: 1, V: 2, B: 2, T: 2 hrs

  • Alternate page-types:

    Enable easy creation of File and Image pages in a wiki.

    We'll do this by including an option in the (new) add-page creation flow. This will be easy, provided that exists.

    E: 1, V: 3, B: 3, T: 2 hrs

  • Regulate basic operations according to roles:

    Implement a basic mechanism by which page owners can designate which roles are allowed to do the following operations on wiki pages:

    • edit (default: members)
    • create (default: members)
    • rename, delete, change parenting: (default: owner)
    • comment (default: members)

    This gives wiki page owners greater content-management control, and can reduce the amount of unintended page-creation cruft.

    (I have not included read-access control here. That would not be a difficult addition, but seems far enough afield from the wiki way that i'm leaving it for after more thought, and proof of need.)

    The designated roles for a new page will default to those of the page from which it's created, implementing a sort of hand-me-down propagation of the policies.

    E: 3.5, V: 5, B: 1.4, T: 6 hrs

  • Implement simple wiki page deletion and rename.

    This needs to be tailored to obey the operation-control permissions.

    E: 1, V: 3, B: 3, T: 2 hrs

  • Expose the differencing of the history capabilities, so people can compare a version of the page since the last visit.

    E: 3, V: 3, B: 1, T: 4 hrs

    (The addition of a comment field to pages, plus the ability for an editor to add comments with commitment of their changes, would enable filtering of change versions to only ones with comments - like seeing versions with checkin log messages...)

  • Create a product by which members can monitor objects on the site for version changes.

    The product would take a list (textarea) of paths to objects to be monitored, and present a page indicating which ones have changed since the user last checked them off as caught-up. (The presentation would have links to the objects, and could craft the links to mark the items as caught-up when the links are traversed.)

    (I can refine some of the stuff i did for tracker reports, here, for obtaining objects according to path.)

    This is an expedient, in lieu of an observer-based notification system and scheduler, by which the user is automatically notified about changes. The nice thing is that it would be usable against any object with a path, not just wiki pages...

    E: 4.5, V: 4.5, R: 1, T: 10 hrs

    (Due to the extraordinary amount of time for this one, i'm going to save it 'til after all the rest, or perhaps find a volunteer to do it - anyone interested, please contact me, i can describe the effort!)

  • Rectify the fundamental structured text and wiki reference bugs.

    Prevent wiki ref substitution for words within sgml tags, and <code></code> and <pre></pre> passages. It'll be a hack, but helpful.

    E: 3, V: 4, B: 1.33, T: 4 hrs

  • Reduce the tendency for the title-bar to spread as you get deeper into a nesting hierarchy.

    I have a simple idea for organizing the title bar differently. Simon what may be a nicer simplification. Jim just puts the nesting stuff below the title bar, which is also worth considering.

    E: 1, V: 2, B: 2, T: 2 hrs

    Result: (2 hrs)

    • Using something like simon michael's approach, where the entry for the current page in the ancestry display is used for the title. I've added a separate backlinks link. I've heard some reservations with the aesthetics of this appoach, but in practice i think it's at least ok, and because of my ugly implementation of the ancestry hierarchy formatting, it's way the most expedient thing.

      This greatly reduces the title-bar spread - it's probably a sign that the nesting is too deep, if it gets wider than the content.

  • Fix the broken SearchPage?.

    E: 1, V: 3, B: 3, T: 2 hrs

    Result: (30 minutes)

    • Had to remove a ! from the form action URL.
    • Applied to SearchPage? original in ZWikiMaker? templates folder. Have to checkin that as .zexp, eventually.
  • Feedback generally useful changes to ZWiki?/simon michael.

Total time: 36 hrs, plus 10 hrs for the biggie

The following items would be nice if there's time.

  • {Maybe} Preview button:

    Provide a "preview" button, by which editors can see the results of their edits side-by-side with the source text, so they can iterate and get it right before committing the changes for release, and freeing up the page for other edits.

    E: 3, V: 1.5, B: .5, T: 4 hrs

Risks

  • As with WikiNG, there is a risk that we complicate the wiki process and sacrifice the fluid, low-impedence benefits that justify use of wiki in the first place.

    Fortunately, all of the changes suggested can be implemented with little or no user-interface impact.

  • There's lots of items, which could take long enough that people would be too disenchanted with wiki before we fix the big problems.

    The solution is to prioritize carefully, to take care of the most objectionable things first (where feasible), and also realize that most of these items are less than a days work. The potential biggies are the notification service and rectification of structured text/wiki ref issues - and the latter may not be big, depending on how bad the mess is and how we approach it.

  • Many of the efforts will be "non-evolutionary" - have to be redone if we want the features in WikiNG.

    This is one cost we may have to accept. The efforts are further prototyping, and should garner experience which will be helpful for the WikiNG effort, even if the code isn't directly useful.

Scope

Biggest bang-for-the-buck in terms of fishbowl process utility, for around a 1 week effort.

Deliverables

  • A prioritization of the solutions, with the aim of ensuring necessary fixes get done. The process may involve eliminating some of the proposed solutions for expedience.
  • New version of our ZWiki? with improvements incorporated.
  • Application of the new ZWiki? version to zope.org wikis. This may include an automatic mechanism for revising existing wiki pages and wikis - necessary particularly if there are changes to standard_wiki_header, standard_wiki_footer, the StructuredText? help page, etc.