forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Noels <>
Subject Re: Project Deliverables List ?
Date Wed, 12 Jun 2002 06:28:57 GMT
Ruedi Anneler - A-R-T GmbH, Switzerland wrote:

> Steven Noels wrote:

>> <ruedi>
>> A graphical representation of the system showing its major components
>> (inputs, main function, outputs) and their collaboration could be of
>> value for newbie navigation. Are you interested in getting a draft to
>> show what I mean and documenting my understanding so far?
>> </ruedi>
>> Yes, please! Seriously! We all like pictures!
> I draw such stuff with Visio 2000, and can export it in different 
> formats. Which format suits best your needs? gif, jpeg, vsd ?

I went through the burden of installing the Visio viewer, but PNG or SVG 
should be the way to go.

> Can I put the drawing in the mailing list? How (is an attachment o.k.)?

We don't have a policy against attachments over here. Beware however of 
limited bandwidth for some of our readers!

> For your feedback: I suggest to draw the changes you like by hand in the 
> graphics I'll send you, and then fax it to me for rework.
> My fax number is 0041 32 353 11 44. Is this procedure o.k. for you? Do 
> you see/prefer something else?

Uh. There wasn't anythin Forrest-specific in the drawing you sent - not? 
For those unable to open the file, I've attached a PNG screenshot.

>> <ruedi>
>> Do you think it's useless to know at least the names, the purpose and
>> the attributes of the project work products?
>> </ruedi>
>> No. But we don't have a full vision on the deliverables (or 'project
>> work products' as you seem to call them). And perhaps we will never
>> have. The next thing you'll be asking is a resource/task list ;-)
> No. For sure not.
> I rode from Canada to Mexico with a mountainbike (in case of interest 
> you can find the story in We have been a group of 12 
> people. 11 of them reached the Mexican Border. There are at least 11 
> very different ways to ride from Rooseville, MT, to Antelope Wells, NM. 
> The agreed by all target location Antelope Wells was of main importance 
> to all of us, not the individual behaviour of any of us on the way to 
> get there :-) .

But you had maps along the road, didn't you ;-) 
(great site, BTW)

> The next thing I will probably ask for is a common denominator of term 
> definitions for better human communication and proper understanding.
> This is normally an external one (e.g. Webster's) for most terms, and a 
> small own for terms defined especially  within and for a certain project 
> or area of interest (e.g. business terms for a certain business area).
> Having such an animal helps to reduce confusion, and to create better 
> understandable documents. This will help some of us as english is not 
> our mother tongue.

You mean a glossary. Yes, having such a thing would sometimes help. I 
often wonder how to call something when composing a mail/document.

e.g. a 'Forrest run': the process of Forrest fetching a subprojects 
documentation sources and processing them using our Cocoon CLI environment

> To give an example:
> A project is a set of activities or a method devised for making or doing 
> something, and achieving an end. It (usually/hopefully) has a limited 
> duration and a defined scope.
> A project work product is the output of a project activity. Its use can 
> be project internal only or project external (within / outside the scope 
> of the project).
> The lifetime of a project internal work product (this is NOT a 
> deliverable of the project) ends with the project.
> A deliverable is a project work product that is delivered by the project 
> contributors to people outside of the project for further use. Its 
> lifetime spans the lifetime of the project (sometimes/hopefully).

Honestly, I don't like this verbiage. While I agree having a common 
understanding of terms like 'project', 'task', 'goal', 'scope' etc is 
beneficial when trying to work as a geographically (and linguistic!) 
dispersed group, I think the basic mode of operations in OSS is quite 
pragmatical: let's assume some common understanding of terms and 
definitions, and if someone doesn't, he/she can always ask the group.

> You told me that there's nothing like e.g. a project management in OSS.
> Could you please define for me what a project documentation is / consist 
> of ?

Hm. Tough question... Diana Shannon (who is also reading this list) 
amongst others isworking on the Cocoon documentation, and has been 
defining a number of content types that make a project's documentation: 
how-to's, tutorials, code snippets or recipes, etc...

A thing which is do find very important is reference documentation: 
authorative documents which is evolving together with design and 
implementation of a system. A thing which is often lacking in OSS, as 
the general tendency is to have this reference docs hidden in the source.

> I assume that the websites you will create will contain knowledge of any 
> kind that is needed by project contributors and project result 
> consumers. If this is the case, your websites will contain a system 
> documentation covering the three main categories technology, processes 
> and (few?) organisation. The main question by creating and maintaining 
> such a documentation are the users needs. This addresses the different 
> views onto the system these people can have, leading to the navigation 
> (static / personalized on a certain level till a very high degree) your 
> website will offer to them. People using a system on the hunt for 
> information to a certain subject enter the website from different point 
> of views, depending on their actual knowledge, activities, problems and 
> need - this might be e.g. an organizational point of view, a technical 
> one or a process oriented one. Static navigation always fails to fulfill 
> these needs in a fast and efficient way - I have practical experience 
> with this (our single information source website offered 8 different 
> navigation patterns - aka views - for eight different user groups 
> working with the same system). A lot of these people were on the lookout 
> for the ninth view. The same is true for static documents containing all 
> three categories and their context too in one information item. My 
> vision is a single sourced information model cosnsisting of single 
> information items describing real objects and their relationships with a 
> high degree of granularity. The web site navigation and the web pages 
> content is bulit dynamically according to the cureent needs of a single 
> user. Such an information model supports all kind of navigation (and any 
> combination of them): alphabet (sequence), time (sequence), category 
> (class), hierarchy, contextual network.
> I suggest to have a closer look on things like WebML, RDF and topic maps.

Interesting thoughts. Topic maps and other metalanguages have been 
discussed already, but not into much length. I fear however that we 
should't impose too much of a burden on document creators. I come from a 
publishing background, and I'm still convinced it is the only industry 
who is able to allocate the budget to do a full-blown TM effort since it 
is part of their core business. For Apache project documentation, a 
linkbase document would already be nice, and having various in-roads 
into the available documentation. We don't want people having to learn 
TM, WebML or RDF before they are able to use Forrest for their project's 
documentation needs (Gosh, I'm being overly pragmatic again, and it's 
getting worse every day - is this the detrimental effect of OSS 
development? ;-)

The idea of having a single sourced information model is very much like 
Maven's POM vision (, 
I believe. IMHO it's the kind of unitary perspective which is bound to 
break: I don't believe in generic metamodels that fit each and every 
case. I'm a firm UNIX pipeline believer, i.e. small, often disparate 
components or artefacts which can be combined to solve a bigger problem.

> The attached drawing probably supports a common understanding. This 
> simple model helped me to save lots of time in many engagements. It 
> tells anybody in the project where we are today and where we want to go 
> the next day. It shows wheter theexpected result/benefit can be reached 
> or not, and it supports the decision wheter it's worth to jump onto the 
> bandwagon or not. Few effort, big benefit.

As I already said, I thought you were going to provide us with some 
Forrest-related drawings.

> It shows a high level view of any kind of cooperative work. To start an 
> engagement I ask the "consumer" of my project work what he likes to HAVE 
> at the end of the project, and try to fill (in this sequence) "Future" 
> (might be visionary and not very "sharp", it is developed further during 
> the project's lifetime according to knowledge gained), and "Now". It's 
> useful to describe the parts givens, expectations, problems, work 
> products and benefit and their attributes in terms allowing to see 
> wheter one has it or not.

Articulating this in an OSS context is one (interesting) thing, having 
people acting upon it however could be rather improbable IMO.


> One last word to this: I'm aware of the fact that most people like to 
> talk about what they want to do (wasted a lot of time in such meetings). 
> Few like to define what they want to have. If anybody has a good 
> explanation for this, I'm really interested in it ;-) .

good point - people have much difficulties describing good use cases, 
but are bound to drool over architectural issues.

> My interpretation of this is that people like to be involved, but 
> dislike to be committed. My understanding of these two terms can be 
> explained with the "beacon and eggs" breakfast. By preparing it, the 
> chicken is involved, but the pig is commited :-D .



> What I've learned is that the things I already know are the only things 
> I can't learn ;-) . Second lesson is that I know a bit less every day of 
> my life.
> I assume that some values of importance for the OSS community differ 
> from the values of the "commercial IT world". I assume that some are the 
> same, e.g. disliking to waste time by answering questions nobody has 
> asked :-D .

Oh well ;-)


View raw message