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