[ZDP] ZDP Awareness Project Update

Maik Roeder roeder@berg.net
Sun, 19 Dec 1999 22:30:15 +0100


Hi !


There are some many changes to the ZDP Awareness Project, and I
would like to hear some comments, especially on the new
"Actions" for the "Roles". 

Also, it would perhaps make sense to have a "Project Folder",
to organize Sub-projects in. I haven't thought much about it,
but it may be worth discussing on the list


Greetings,

Maik Röder



   Version History

   Version 0.4 19 Dec 1999
   
      Not changed:

         - I have not yet updated the Object model - It still
           needs much more work ! I am not sending it in this
           mail.
   
      Changes:

         - Almost all information has been moved from the extension
           to the Requirements specification. So we get a better
           overview of what should be done, no matter if it can be
           done in the first version.
         - Introduced the Role "Self", to make a difference between a
           someone with a "Member"-Role viewing another Member, and
           a person with "Self" Role looking at himself.
         - Member information is now split into externally visible
           information, internally visible information and information
           only visible by Self and the Admin.
         - Member information is only editable by the member except 
           for the granted roles, which is editable by the Admin
           only
         - Actions added  ! I must admit that I quite misunderstood
           what a Role really means. This is why I added a "Deleter"
           role, which is humbug. There is a Role "Admin", which 
           allows a person with this role to apply the "Action" of
           "Delete Document" to a document.
         - There are now Roles which can be taken in different contexts
           Contexts are "Development of a Document", "View Member 
           information", "User Aministration", "Member Activity",
           "Viewing Documents", "Searching Documents", "Organizing
           Documents"
         - Posted to the ZDP mailing list as "ZDP Awareness Project
Update"

      New in Extensions

         - active/inactive members in Additional Summaries of the
           status oder a period of time
         - some new Summaries of the current status
     
      Ideas
         - We could use a Project folder, where we can manage
           projects like the ZBook. This would make the ZDP project
           more manageable (divide and conquer). I won't elaborate
           too much on this, but this looks like a really promising
           idea !!!
         - We also need some kind of folder anyway, because a
           document not only consists of a single text. The reason 
           for overlooking this problem is that we started our
           project with the vision of managing Drafts. Drafts
           are in their early state really just flat text files.
         - There could be a personal Draft folder, where members upload
           their Documents. Maybe this is not needed, because
           people can organize their stuff on their own ?
         - Tom Deprez  has the idea to
           create a News Items every time an action like "Create 
           Document" or "Change Document" happens. The News item would
           be put into a News Folder. There could be a Activity View
           showing all such News. Also, when a news item gets older,
           it could be moved to a summary object and deleted from 
           the news folder. Summary object could be viewed too.
         - Notifications could be sent to people who need to be
           kept up to date on what happens in their project.
         - Tom Deprez  had the idea that 
           Requesters, Questioners can publish their Email address
           along their Request or Question and be notified when
           something happens concerning their request
         - Tom Deprez  suggested that
           voting of what documentation is needed should work the
           following way: People search for something, and get as
           a result also the questions which may not be yet answered.
           They can vote by giving their email address and push on
           a vote button of the question. This would reduce the amount
           of questions on the same topic dramatically, because people
           looking for an answer already see the questions of other
           people who want to know more on the topic. Really cool !
         - Tom Deprez  elaborated om the
           problem of an activity metric: "We can ask every document
object
           it's latest modification date (I think this is a function in
           Zope). If we allow every object to have keywords for the
           writer/editor/..., we can search the whole Zope document
           objects to objects on which the person is working. Looking at
           the latest modification date allows us to give some sort of
           activity knowledge.
         - Tom Deprez  made clear what
           Editors and Writer roles mean:
              1. A person, becomes a writer when he publishes a draft
              2. We can also make a certain "wait-for-publishing-list"
              3. The draft is made public when a 'manager' allows the
draft)
              4. The writer decides when the draft is ready for editing.
              5. An editor takes the draft on him/her
              6. The editor makes the draft to a 'finished' product
                 according to the style-guide of ZDP.
              7. Only the Writer and Editor are allowed to change the
                 draft on which they are working.
              8. Other people can only give comments to the draft
                 (comments which are linked to the draft). 
              9. The writer and editor will take these comments
                 into account and changes the draft.

      Design Decisions
         - Documents need to be kept in a Folder, because a Document
           is more than just a flat ASCII file which could be saved
           in the property of a Zope document.
         - This would allow to beautifully store comments on a
           document inside the document :-)

      Discussion
         - Voting System Discussion: Tom Deprez 
           and Rik Hoekstra  both think that
           a voting system on what documentation should be worked on is
           a good idea. People who want an answer to a question can vote
           for it.
         - Versioning Discussion: Tom Deprez 
           noted that "we could give the document a property in which a
           version number must beentered (=major version). We can also
make
           an intern version number (how many times the object is
changed,
           I think this is possible in Zope)." Well, I think versioning
           is not really an issue here, as I said before versioning can
be 
           done inside a document. What do the others think ?
         - Activity Metric Discussion: Tom Deprez 
           elaborated on the  problem of an activity metric: "We can ask
           every document object it's latest modification date (I think
this
           is a function in Zope). If we allow every object to have
keywords
           for the writer/editor/..., we can search the whole Zope
document
           objects to objects on which the person is working. Looking at
           the latest modification date allows us to give some sort of
           activity knowledge." I think that things are not so easy, and
           that we still need to do more research on the topic !
         - Linking Comments to Documents Discussion: Tom Deprez
            said that Documents should contain
           a link to a comment. Comments can have a link to a comment
           and so on.  In my opinion this is already an implementation
           decision. Instead, I made the design decision to declare a
           document to be a folder. Inside the folder the comments can
           take place. Comments can easily be removed, and showing
documents
           in the context of a document is easy too.

      TODO:
         - Tom Deprez  noted that "We should
           start to think on the possible keywords, Categories!"

   Version 0.3 18 Dec 1999

      Changes:

         - 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 and updated
           Requirements Specification Draft"

      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 
         - 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 
         - Added Snippet Answer to Document  as a Document Type
           Suggested by Rik Hoekstra 

      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  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  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  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  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  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  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  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  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  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  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  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  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

      Changes:

         - 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 "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  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

      Changes:

         - Posted Specification of the problem domain to the ZDP mailing
list as
           "Joining ZDP ! - Starting a new project."
   
   Requirements Specification Draft

      Contributors:
         Tom Deprez 
         Rik Hoekstra 
         Patrick Phalen 
         Emmanuel Rousselle 
         Maik Röder 

      Influenced by:
         - Postings from "Jim Salmons"  on the ZDP list
           in August 1999 and replies to these by "Martijn Faassen" 
           .
 
      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

      Problem Description:
   
         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

      Member Information

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

            Externally and Internally visible information         

               1. Login name
               2. Public Email

            Internally visible information
              
               1. Full Name
               2. Internal Email
               3. Fields of Interest/Expertise
               4. Granted Roles
               5. State

         Information only visible to the Admin and to Self

               1. Wanted Roles

         The following information is only editable by the Admin:

               1. Granted Role

         All other pieces of information are editable by the Member
         only. The Admin has the potential right to edit any Member
         information, but should restrain from doing so unless there
         is a very good reason to do so. For example changing the
         status of a member could be ok if the person has been absent
         from the project, while his status says he is working on
         the project.
            
      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

      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
 
            Text: 

               1. The actual content of the document.

            Text type: 
 
               1. Structured Text
               2. ASCII
               3. XML
               4. HTML

            Keywords:

               1. Stuff like "ZPTK", "Methods" or "ZCatalog"

            Document Type:
 
               1. Draft
               2. How-To
               3. Question
               4. Snippet
               
            Category
               
               1. General
               2. Databases
               3. Security

            Needs:

               1. Reader
               2. Writer
               3. Editor
               4. Approver

            Maintainer: 
               
               1. Login Name of the Maintainer

            Writers: 
            
               1. People who are writing on the document

            Comments
               
               1. Stuff like "Cool !",  "Great stuff !" and "Unreadable
!"

      Actions on Documents

         There are several Actions, which a Member of the ZDP projects
         can take on Documents.

            1. Read Document
            2. Submit Document
            3. Write Document
            4. Delete Document
            5. Approve Document
            6. Review Document
            7. Delete Document
            8. Recategorize Document
            9. Move Document
            10. Become Maintainer
            11. Decome Writer
            12. Add Comment
            13. Delete Comment

      Actions on Members

            1. Edit Login Name
            2. Edit Public Email
            3. Edit Full Name
            4. Edit Internal Email
            5. Edit Fields of Interst/Expertise
            6. Edit Granted Roles
            7. Edit Status
            8. Edit Wanted Roles

      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. 

         Roles in the context of developing a Document of any kind:

            - Questioner            - Asks a question
            - Requester             - Asks for a piece of documentation
            - Contributor           - Submits a Draft work
                                    - Asks for Review
            - Editor                - Edits written Documents
            - Subject Matter Expert - Reviews a Draft work
                                    - Asks for Approval
            - Project Manager       - Approves a reviewed Document
                  
         Roles in the context of viewing Member information are defined
by
         what pieces of information the People who have the Role can
view.
  
            - Visitor - Views externally visible information
            - Member  - Views what a Visitor is allowed to view, and
                        additionally has the right to view internally
                        visible information.
            - Self    - Views all personal information
            - Admin   - Views all personal information

        Roles in the context of "User Administration"
            - Self  - Keeps his personal information up to date, but can
not
                      change the Granted Roles himself.
            - Admin - Can potentially change all Member information, but
                      generally only edits the Granted Roles, while
under
                      certain circumstances he may edit the status of a
                      member. 

        Roles in the context of viewing "Member Activity" - who is
working
        on the ZDP project.
         
            1. Visitor - Can not see active and inactive Members
            2. Member - Can see active and inactive Members

        Roles in the context of viewing documents
 
            1. Visitor - Can view all of the document, but only as much
of
                         the Member information as is allowed by the
                         Visitor Role
            1. Member - Can view all of the documents

        Roles in the context of searching in documents

            1. Reader - Can search documents by type, category, keyword
                        and search term

        Roles in the context of keeping the documents organized

            1. Librarian - Can organize the documents in categories
                           and also delete obsolete Documents or
                           split Documents.

   Extension to the Specification:

      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
            7. active/inactive members

      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
            4. Show all members + Roles + Status
            5. Show all drafts + author + date
            6. Who is doing what: author + draft + date
            7. Show all drafts
            8. Show all submitted drafts/edited drafts ...