[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