[ZDP] Object Model of said project

Maik Roeder roeder@berg.net
Sat, 18 Dec 1999 03:18:15 +0100


Hi !


Thanks for the comments and suggestions from the people
who have taken the time to reply to my postings ! I am 
replying to them in an extra section further down.

I have developed a first object model, using CRC cards,
which you can see directly when you scroll to the end
of this Email. For people who are interested, there  
is  a link to the original paper about "Class,  
Responsibility, and Collaboration" cards in the References
section.

I have done some restructuring and rethinking of the
Requirements specification. The changes are not really big,
but to make sure people can get a quick overview, I have
documented the changes in the Version history.

I hope to start the implementation soon, if there are no
objections ;-)

BTW, what is the maximum size of a post you can possibly
accept on this list ? Do I need to put the things up
on the ZDP homepage, and just send a notice on the list ?

Please let me know what you think !

Greetings,

Maik Röder


Version History:

Version 0.3 18 Dec 1999
   - Added a link to an introductory article on Design Techniques
     in Reference Section
   - Created an object model using CRC cards
   - Added a link for information on CRC cards in Reference Section
   - Reworked Summary section, which now is more about awareness
     of members and documents
   - Moved Reader Role back to Requirements Specification
   - No more Manager Role because a manager can up to now only
     delete documents, so he fulfills only a Deleter Role.
   - A Draft becomes a Document Type of a Document.
   - Documents get keywords
   - Documents get a Text type
   - Documents get a Category
   - Documents get Comments
   - Added Editor to Extensions
   - Role of Reader defined better
   - Posted Requirements Specification Draft and Object Model
     to the ZDP mailing list as "Object Model of said project"

   New in Extensions:
      - Added wanted/allowed roles to Person
      - The role of a "Mover" is someone who moves documentation around.
      - Editor - Someone who edits existing Documentation
        Suggested by Rik Hoekstra <RikHoekstra@bigfoot.com>
      - Some more possible choices for Document information in the
        Extension.
      - Role Changes replace the original implicit Role assignment
        An Admin grants the more important roles. Members can apply
        for a new role. Reader role is free :-)
      - Documents get Comments
      - Documents get a Maintainer
      - Added Snippet Request to Document as a Document Type   
        Suggested by Rik Hoekstra <RikHoekstra@bigfoot.com>
      - Added Snippet Answer to Document  as a Document Type
        Suggested by Rik Hoekstra <RikHoekstra@bigfoot.com>

   Removed from Extensions
      - Implicit states are just searches. In the examples, a 
        view of Members who are working on a draft that needs
        reviewers is no more that a search for Documents with
        need for Reviewers. We get the Author for free from 
        the search.
      - Implicit Roles have been removed
      - Becoming an implicit Reviewer for example is replaced
        by an Admin granting this role. Of course anyone can
        become a Reader and a Writer, but I don't think we are   
        in need of too many implicit Deleters, are we ? :-)
      - Incomplete Documents removed from extensions. Needs
        for Readers, Writers, Reviewers now come directly
        with the Documents as "Needs"

   Ideas:
      - A person can ask for a new role
      - The ZDP admin can allow a role
      - The ZDP admin needs a view of Persons who want a new role,
        or want to step down from a role.
      - There could be the role of a "Mover" someone who moves
        documentation around.

   Discussion:
      - Patrick Phalen <zope@teleo.net> said, we should have a
        look at the Xen project management system written in Zope
        at http://bits.netizen.com.au/Xen/
        I have not downloaded it, but from what I have read on the
        homepage, it is a much more rigid system than we are
        planning here. We are talking about ad hoc collaboration,
        while Xen is thought for project management.
      - Patrick Phalen <zope@teleo.net> said that QAML a Meta
        Language meant for FAQs. It is available at the address
        http://www.faq.org/qaml/
        We might have a look at it later.
      - Emmanuel Rousselle <eroussel@maestria.com> suggested to
        have a look at the Web-based application EProject, which is
        available for free at http://www.eproject.com. It might
        help define more precisely the functions needed from
        such a tool.
      - Rik Hoekstra <RikHoekstra@bigfoot.com> asked if the idea
        of a "View of what kind of documentation is requested most."
        would include a voting system. Well, I don't think that this
        is necessary. I think the view is sufficient. Writers can
        pick the stuff they want to write about. If there are
        like 10 requests to write about how to get PCGI working,
        then this would be some kind of a vote. Requests could
        be put in categories, so when someone has actually written
        a document about the topic, he can contact all the Requesters
        which would be really cool.  
      - Rik Hoekstra <RikHoekstra@bigfoot.com> asked how we
        determine when someone is active. The first implementation
        will only check for a person's own statements. There can
        be some kind of a activity metric in the future, but some
        research has to be done before.
      - Rik Hoekstra <RikHoekstra@bigfoot.com> asked whether subsequent
        versions of a draft be numbered automatically? I would say
        versioning should be done in the document itself. This gives
        a greater degree of freedom, I think.
      - Rik Hoekstra <RikHoekstra@bigfoot.com> asked who has the
        authority to change a draft ? In my opinion, you have to
        get the role of an editor assigned by the administrator

        of the ZDP project. You can ask for a role by putting it
        on your wanted roles list. The Admin can see all people who
        want a certain role, and grant it or deny it. This is stuff
        for a later version. Right now everyone can do everything.
      - Rik Hoekstra <RikHoekstra@bigfoot.com> asked, how people
        get involved with a Draft. I think that the author of
        a Draft can put the Flag "Needs editor", and everyone who
        is an editor can take this role, and edit the draft. The
        author knows best when his draft is ready for prime time,
        so someone who takes the Editor Role before the Draft is
        ready would not do a favour to the project. But it
        would be ok to take the Editor role, when author of the
        document is absent from the project, and you have asked
        the Admin to put a "Needs Editor" Flag on the Draft.
        This is stuff for a later version, but great stuff indeed !
      - Rik Hoekstra <RikHoekstra@bigfoot.com> noted that sometime
        ago there was a discussion about snippets, which are Requests
        for Small code examples. Well, I think we only need to
        create a new Document Type "Snippet", and allow Requesters
        to ask for specific Document types.
      - Rik Hoekstra <RikHoekstra@bigfoot.com> asked whether a Reader,
        which was defined as "Someone who can currently look at new
Drafts"
        is an Editor? I did not think of a Reader as an Editor. I just
        introduced this Role to grab someone who is not a Member of
        The ZDP. There is a special view for Readers. For example they
        are not allowed to see the internal Email of ZDP members.
      - Rik Hoekstra <RikHoekstra@bigfoot.com> stated that the people
        who have roles concerning a specific document should be shown in
        association with the document. This is a good idea, because this
        way there could be just one Editor to a document.
      - Rik Hoekstra <RikHoekstra@bigfoot.com> said that People who
        take a Role in the production of a Document should be
        associated with the Document. I would say that it makes sense
        to associate a Maintainer with a document. Also, Writers
        can be associated with documents.

Version 0.2 17 Dec 1999
   - The domain objects of this Documentation project are Documents,
     and so I rename Drafts to Documents. The Documents can evolve to
     different Document Types. An empty document can evolve to a
     request for documentation, which can evolve to a chapter in
     a the Zope Book, or maybe it evolves to an How-To. For the
different
     Document Types we get Document Type Definitions, so called DTDs :-)
   - Specified document types - Just Draft for now.
   - Posted to ZDP mailing list as "Announced Project's 
     Requirements Specification Draft"

   Things that have been moved to the Extension of the Specification,
   because they would complicate things too much:
      - Right now everyone is a potential Writer and a Manager of the
        ZDP site, so the only role for now is that of a Manager who can
        basically do all the things that the other roles can do, so

        diversifying roles can be worked on in a later phase.
      - Incorporated an idea of Patrick Phalen <zope@teleo.net> to have
a
        role of a Requester, who asks for documentation. He also
suggested
        to have a view of what kind of documentation is requested
      - This reminded me there could also be a Questioner, someone who
        asks a question.
      - Implicit roles
      - Implicit states
      - Showing the roles of members in a summary
      - Documents that need a special role
      - Showing all documents in need of a person who could take a
certain
        role.

   Ideas:
      - View of what kind of documentation is requested most.
      - If we have a Requester we could use a Questioner too - someone
        who asks a question.

Version 0.1 16 Dec 1999
   - Posted Specification of the problem domain to the ZDP mailing list
as
     "Joining ZDP ! - Starting a new project."

Contributors:
   Tom Deprez <tom.deprez@village.uunet.be>
   Rik Hoekstra <RikHoekstra@bigfoot.com>
   Patrick Phalen <zope@teleo.net>   
   Emmanuel Rousselle <eroussel@maestria.com>
   Maik Röder <roeder@berg.net>

Online Resources:
   Object Oriented Design:
      - Bill Venners "Introduction to "Design Techniques"" Javaworld,
February 1998
       
http://www.javaworld.com/javaworld/jw-02-1998/jw-02-techniques.html
   Introduction to CRC cards:
      - Kent Beck, Ward Cunningham, "A Laboratory For Teaching
Object-Oriented
        Thinking", OOPSLA'89 Conference Proceedings, 1989
        http://c2.com/doc/oopsla89/paper.html

Requirements Specification Draft

      The Problem at the moment is that it is very difficult see who is
still
      active on the ZDP and what people are doing, because people are
      working together in an ad hoc fashion, so there is a lack of
      awareness. To raise the level of awareness,  in such a big
collaborative
      project, the ZDP members will get acess to all sorts of activity
summaries,
      which will be linked from the main ZDP page.
      It is to be hoped that once the ZDP project is better organized,
contributors
      will be more motivated, as their effort is actually noticed by the
other
      project members.

      Awareness about what is going on in the ZDP project

         Who is working on the ZDP project ?

            1. Show active members
            2. Show inactive members 

         Search in documents

            1. Show documents by type
            2. Show documents of a category
            3. Show documents of a keyword
            4. Show documents by search term

      Person Information

         ZDP Members give some personal information. Some information
         may be given by the ZDP manager only, like allowed roles.
         Wanted Roles should be visible by the manager in a view.

            1. Login name
            2. Internal Email
            3. Full name
            4. Company
            5. Public Email
            6. Fields of interest/expertise

      Roles

         ZDP members can assign roles for themselves which indicate what
kind
         of roles they are capable to take. According to the "open book
model",
         the skills of the ZDP members are visible to all ZDP team
members,
         but possibly hidden for non-members. The roles define what
action
         the members can take on the Documents.

            1. Reader - Reads documents but is not an Editor.
                        A Reader someone who is not a member of the ZDP.
            2. Writer - Writes documents
            3. Deleter - Deletes documents

      Documents

         ZDP members can create a special Document object of some type.
         Documents can be enriched with keywords to allow for searching.
         More Text- and Document-Types and Categories in the Extension

            1. Text: The actual content
            2. Text type: Structured Text
            3. Keywords: ASCII Text  
            4. Document Type: Draft
            5. Category: General     

      State

         To track the status of ZDP members in the summaries, people can
change
         their state of involvement. 

            1. Working on an unpublished draft
            2. On holiday
            3. Private
            4. Too busy

   Extension to the Specification:
                                     
      Here I gather thoughts which came up while writing down the
      specification, but which make things too complicated right now.

      Additional Person Information  

         1. Allowed Roles
         2. Wanted Roles

      Additional Roles

         1. Questioner - Asks a question
         2. Requester - Asks for a piece of documentation
         3. Editor - Edits written documents
         3. Reviewer - Reviews documents
         4. Mover - Moves Documents around

      Documents

         Some more possibilities for document information:

            1. Text type: ASCII, XML, HTML, ...
            2. Keywords: ZPTK, Methods, ZCatalog, External Method, ...
            3. Document Type:
               1. Draft
               2. How-To
               3. Question - Question to be answered in a FAQ
               4. Snippet Request - Request for a piece of code
               5. Snippet Answer - A piece of code
            4. Category: General, Databases, Security, ...
            5. Needs: Reader, Writer, Reviewer, Deleter, ...
            6. Maintainer: Name of the Maintainer
            7. Writers: People who are writing on the document
            8. Comments: Cool ! Great stuff !

      Role Changes

         The roles of the ZDP members can change when an Admin
         gives a new role. A ZDP member can also apply for

         a new Role. Some roles are for free, like Reader
         Role or Writer Role, but a Deleter Role is not
         available to everyone.


      Additional Summaries of the status over a period of time

         The following summaries about what has happened in the ZDP
         project over the last week, or any period of time, is shown
         publicly on the main ZDP page. For the given period of time
         show all

            1. new Drafts
            2. new members
            3. status information changes of members
            4. role changes of members
            5. all request for documentation
            6. all questions

      Additional Summaries of the current status

         The following summaries will be available for ZDP members.

            1. Show requests for documentation
            2. Show questions
            3. Show drafts in need of someone who takes a certain role


   Object Model

      The object model has been created using CRC Cards. I will present
the
      model bottom up, first showing the Model, then the Controllers and
      then the Views.

      Person
      ------

         Responsibilities

            1. Maintain login name   
            2. Maintain Internal Email
            3. Maintain Full Name
            4. Maintain Company
            5. Maintain Public Email
            6. Maintain Fields of Interest
            7. Maintain Fields of expertise

            8. (Maintain allowed roles)
            9. (Maintain wanted roles)
            10. (Maintain status)    


         Collaborators

            1. None

      Document
      --------

         Responsibilities

            1. Maintain text
            2. Maintain keywords
            3. Maintain writer
            4. Maintain type
            5. Maintain category

            6. (Maintain Maintainer) ;-)
            7. (Maintain Writers)    
            8. (Maintain needs)

         Collaborators

            1. None

      Document Controller
      -------------------

         Responsibilities

            1. Create document
            2. Delete document
            3. Read document Information
            4. Change document Information

         Collaborators

            1. DocumentView

      Person Controller
      -----------------

         Responsibilities

            1. Change person information
            2. Read person information
            3. Read person status
                                     
         Collaborators

            1. Person View


      Document View
      -------------

         Responsibilities

            1. Show Document as Text 
            2. Show Edit Button
            3. Show Delete Button    

         Collaborators

            1. Document Controller   

      Person View
      -----------

         Responsibilities

            1. Show login name
            2. Show internal email
            3. Show full name
            4. Show company
            5. Show public email
            6. Show fields of interest
            7. Show fields of expertise

            8. (Show allowed roles)
            9. (Show wanted roles)   

        Collaborators

            1. Person Controller

      Document Search View
      --------------------

         Responsibilities

            1. Show Documents by type
            2. Show Documents by category
            3. Show Documents by keyword
            4. Show Documents by search term

         Collaborators

            1. Document Controller   

      Person Awareness View
      ---------------------

         Responsibilities

            1. Show active Persons   
            2. Show inactive Persons 

         Collaborators

            1. Person Controller

      Activity View
      ------------------

         Responsibilities

            1. Show Write Document Button
            2. Show Search Document Button

            3. (Show Ask Questions Button)
            4. (Show Request Document Button)

         Collaborators

            1. Document Controller