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:[EMAIL PROTECTED] > Sent: Tuesday, August 26, 2003 12:54 PM > To: [EMAIL PROTECTED] > 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 >
