cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Chris Clark" <Chris.Cl...@teranet.ca>
Subject RE: Personality in docs (Was: Re: 'Production' build for Cocoon?)
Date Tue, 26 Aug 2003 17:13:48 GMT
Being the guy that started this little storm I thought I'd wade in with my 2 cents worth...

I don't mind the humour in the install.txt.  I thought it was refreshing to see somebody who
admits that by-and-large, developers hate reading docs and would rather just dive in and figure
it for themselves.  Granted, if the reader is not a developer, but somebody less tech-savvy
(say, a Project Manager) then I could certainly see where the humour could be lost on them
and make a bad first impression.

I think everything could be improved with slightly better organization.  I was looking for
information on building a "Production" build.  So I looked for build or deploy documents.
 I didn't think of going back to the install.txt (after all, I had already installed it, right?),
although I had read the entire file when I downloaded and installed it the first time.

If it were up to me (and yes, I know it could very well be if I had the time!), I would create
a readme.txt that would point the user to one of install.txt, build.txt, deploy.txt and maybe
an overview.txt or welcome.txt.  The install could be left pretty much the same (just make
sure there's a link to the website with all the version-specific helps).  The build.txt could
cover the modifications to the local.build.properties and maybe go into a bit more detail
(sentence each) on what the various things control.  The welcome/overview could be targeted
at the less tech-savvy crew (with appropriate language/tone).

So, my vote would be to keep the personality, just flesh out what's there a little more and
maybe make a concessionary personality-free doc for the non-developer audience that expects
sterile business language.

Cheers,
Chris

> -----Original Message-----
> From:	Tony Collen [SMTP:colle006@umn.edu]
> Sent:	Tuesday, August 26, 2003 12:54 PM
> To:	dev@cocoon.apache.org
> Subject:	Personality in docs (Was: Re: 'Production' build for Cocoon?)
> 
> Roger I Martin PhD wrote:
> 
> > Right now INSTALL.txt needs some things cut out of it:
> 
> [stuff-snipped]
> 
> I'd like to point out a few Theses of the Cluetrain which apply here:
> 
> 14. Corporations do not speak in the same voice as these new networked conversations.
To their 
> intended online audiences, companies sound hollow, flat, literally inhuman.
> 
> 15. In just a few more years, the current homogenized "voice" of business> -> the
sound of mission 
> statements and brochures> -> will seem as contrived and artificial as the language
of the 18th century 
> French court.
> 
> 16. Already, companies that speak in the language of the pitch, the dog-and-pony show,
are no longer 
> speaking to anyone.
> 
> 17. Companies that assume online markets are the same markets that used to watch their
ads on 
> television are kidding themselves.
> 
> 18. Companies that don't realize their markets are now networked person-to-person, getting
smarter 
> as a result and deeply joined in conversation are missing their best opportunity.
> 
> 19. Companies can now communicate with their markets directly. If they blow it, it could
be their 
> last chance.
> 
> 20. Companies need to realize their markets are often laughing. At them.
> 
> 21. Companies need to lighten up and take themselves less seriously. They need to get
a sense of humor.
> 
> 22. Getting a sense of humor does not mean putting some jokes on the corporate web site.
Rather, it 
> requires big values, a little humility, straight talk, and a genuine point of view.
> 
> I don't mind making the docs a little more "pofessional sounding" but I'd really, really
hate to see 
> the personality stripped from them as well.  We're all people here, not robots.  I'd
rather read 
> someone's genuine opinion about why Cocoon kicks so much ass instead of reading about
the latest 
> buzzword of the day.
> 
> 
> Tony
> 

Mime
View raw message