[Grok-dev] Idea for a new tutorial - need feedback

[Steve Schmechel]

I am going to begin working on a multi-part tutorial that will follow
the course of building a small web application using Grok.  I hope that
this will bring together several aspects of working with Grok that are
covered in more detail in separate tutorials and how-to documents.

Some Background 
---------------

I have followed the development of Grok for quite a while (early 2007)
and tinkered with it here and there, but I do not have an opportunity to
use it as part of my job so it has never gotten to the point of feeling
"natural" to me.

As part of my volunteer work with some non-profit groups, I have used
and extended Plone to provide solutions to various problems.  This has
provided me with some exposure to Zope and Python, but I am certainly
not an expert in any of those areas.

My professional work is composed of large-scale development, with layers
of requirements, tricking in through slow, bureaucratic channels.  It is
really fun for me to volunteer to do some small projects, where I can
see results quickly.  I see Grok as a great way to quickly try out a
solution and get user feedback.  You can develop in an agile way and at
the end have something that is more than just a prototype.

I currently have an opportunity to help out a group of volunteer
musicians with organizing information about their performances within
their group.

The requirements are fairly simple and there are certainly many ways
this could be accomplished.  Customizing a Plone site seems like
overkill.  A small, dedicated solution would help them AND provide a
nice learning experience for myself and others.

There is no hard time frame for completing the solution, and while I
have expanded the requirement to try to cover a lot of possible
functionality in order to enhance the learning experience, the group
would be happy with even the most basic system. 

What I Hope to Accomplish 
-------------------------

I would like to create a tutorial that includes some "hard-earned
wisdom" on practical things like organizing your source code and other
artifacts within a project, using the debugger, writing and running
tests, etc.  These items are often glossed over in other documentation
for the sake of simplicity, but when you want to sit down and do a
bigger project and you haven't stepped through the practical 
"nuts and bolts" a few times, you can feel lost.

I want the pieces of the tutorial to follow a progression, with each
piece building on the next.  Starting from a simple model and prototype
and evolving the way a real project might.  For someone who makes a
living doing Zope/Grok style development, this might seem tedious and
may not match their personal work style.  My target audience are those
with little or no experience in this type of development who are trying
to get into Grok to do something useful.

What I Could Use from The Grok Community
----------------------------------------

- Feedback on the requirements included below (in ReST format).  I think
  they cover many of the key aspects of Grok programming.  (Traversal,
  forms, searching, static files, security, AJAX, etc.) Can you think of
  other areas that could be taught within these requirements?

- Ideas on the best approach to take when there are several
  alternatives.  (Templating, AJAX, etc.)

- Help when I get stuck.  Everyone here is already great at helping
  others.  The community around Grok is one of its most attractive
  assets.  Thanks in advance.

- A place to put the tutorial as it is written.  I currently don't have
  write access to the documentation site.  Let me know what I need to do
  or who I need to talk to.

- Feedback on the tutorial as it evolves.  As I finish significant
  sections I will either prompt the list or, if there are certain
  individuals who are more interested than others, I could notify them
  more frequently and let others review it whenever they feel like it.


Thank you for taking the time to read all of this.  I hope what I write
will be of benefit to the Grok community and make it easier for new
developers to "grok Grok".

---------------------------------------------------------------------

===============================
Musical Performance Application
===============================

Description
===========

In some venues, ad-hoc bands of musicians and vocalists come together to
perform at scheduled events.  The band leader for a given event needs to
organize the people involved, develop the list of music they will
perform, and distribute sheet music, chord charts, and lyrics.

A leader may be in charge of several performances involving different
musicians.  Likewise, musicians and vocalists may be involved in several
performances lead by different people.

Currently, much of this organization is done via email.  As expected,
often key people are missed in the email distribution or their email
address changes or their account is broken, causing them to miss
important information.  

Even if they receive all the information, it is still possible for them
to mis-file the emails or attachments.  Often updates for various
performances come "out of sequence" and, if the subject is not very
clear (i.e. "Friday's Performance" instead of a distinct date), the
recipient can get confused.

Having a web site that lists all the important information and allows
them to download the files they need for their preparation would be a
benefit to everyone involved.


Entity Outline
==============

- Application Root (contains Performance objects)

  - Performance

    - Date

    - Location

    - Leader

    - Musicians (contains Musician objects)

      - Name
    
      - Email Address

      - Instrument

    - Set List (contains Song objects)

      - Song Title

      - Arrangement Notes

      - Display Order

      - Attachments (contains Resource references)

        - File Name
    
        - File URL
    
        - File MD5 Hash (Hidden/Optional)
    
    - Comments (Contains Comment objects

      - Date
    
      - Author Email Address
    
      - Comment Text


General Requirements
====================

- Performances should be organized by date.  Since it is possible to
  perform more than once in a day, an optional, "rough time" can be
  added to the day to differentiate them.  Performances will never
  happen more frequently than once per hour.

- Performances should be able to be found by URL's that can be
  understood to refer to a certain performance.  Example:
  http://example.com/TheBandName/2009-03-05/

- Users should be able to upload files in any format they choose (PDF,
  DOC, Text, etc).  No special handling or MIME types are provided by
  the application to enhance browser interaction.


Phased Deliverables
===================

Phase 1 - Basic Functions
-------------------------

All current and future performances are listed
  Sorted ascending by date.

Text-field forms
  User hand-types dates, musician names, song names, and display order 
  relying on web browser for any form completion efficiencies.

Basic file upload support
  Upload to a static directory or BLOB resource directory.  
  Always upload user selected attachments and use a "name-chooser" to
  prevent overwriting existing files.  Deleting an attachment releases 
  any storage space used by the file.

No user authentication, roles or permission support.
  Rely on external security via web proxy configuration or rewrite rules.

Basic Text Comments
  Anyone can comment.  No email support or comment-spam protection.

Phase 2 - Improved Usability
----------------------------

Enhanced Performance Listing
  Ability to see past performances.  More display of summary performance 
  details such as simple musician and song listings.

Form Widgets
  Use of date-picker, and drop down lists to speed selection of information
  that already exists in the application.  Buttons or "Drag and Drop" to
  adjust display order.

Enhanced Upload
  Ability to quickly select more than one attachment item.  
  Warn user when an attachment may already exist and offer to link to the 
  existing file rather than uploading another.  (This could be done by
  file name matching or possibly a file content hash comparison.)  
  Only remove underlying file content when no attachments (in any 
  performance) reference the file.

Basic Roles for Editing 
  Leader role can create Performances and add songs to Set list.  
  Assistant role can modify existing song arrangement notes and 
  add/remove attachments.

Email Support for Comments
  Basic comment-spam protection via capcha or email confirmation request.
  Notification email with URL of this performance sent to the addresses 
  of all associated musicians.

Phase 3 - Style and Management
------------------------------

Create a stylized look for the site.
  Use a template system, CSS, and some images to give the site an appealing
  look.  Should be easy to modify the colors and any logos via CSS edits.

Application Search
  Ability to search or filter performances by song performed or musicians
  involved.

Provide Management Functions
  Removal or archiving of past performances.  Attachment management to 
  free storage resources.