Zotonic Documentation
ll...@writersglen.com
I'm taking the liberty of responding to your outline through the Zotonic dev list for an essential reason. The developers know Zotonic inside and out. They better than anyone will be able to help us as writers convey what adopters and users need to know. I understand that the developers have made a major commitment to generate world-class documentation for Zotonic and, no doubt, much of their thinking is reflected in the outline. And this is good. Because if the developers are not 110% invested in doc development, then the effort WILL fail.
I haven't had a chance yet to reflect deeply on the content and structure of the outline. But, quick read-over, it seems to cover most of the essential areas. But I have some concerns.
First, I think much more effort needs to go into parsing the content across key audience segments. We're all so busy with our lives that when faced with a project or task we want to get to the nitty-gritty as fast as possible and see immediate, if not sooner, results.
So let me propose seven adopter/user cases:
1) Sarah the Marketing Manager
Sarah needs a website for her start-up. She wants a CMS that can grow with her red-hot company. She needs to sell Zotonic to the big boss.
2) Jess the Web Developer
He's in business to make money. He's discovered the hard-way that clients are increasingly reluctant to pay for the long and tedious hours that quality web development entails. He needs to train his people.
3) Bogart the Graphic Designer
Jess needs to bring Bogart on-board to successfully adopt Zotonic as his firm's principal platform.
4) Erica the Product Manager
Erica has to enter product descriptions into the company's CMS as fast and accurately as possible. She also maintains a blog for technical users of her company's products.
5) Walter the IT guy
Sarah needs Walter's buy-in to sell Zotonic to her boss. Walter needs to install and maintain this puppy across a global network. He's a Microsoft guy so suspicious from the get-go.
6) Yurii the Erlang Guru
He wants to blow the socks off the Erlang community with wicked new Zotonic features and capabilities.
7) Lloyd the Indie Publisher. He can't afford professional web consultants. But he needs to develop book sites, blogs, and management tools and can't spend much time doing it.
Now, given these seven prospective "customers," how do we parse the content in the outline to deliver just what each needs to know when they need to know it in the clearest most engaging way?
Thinking this way suggests that one monolithic document may not be the best way to go. It may be good to have such a document as a content base, but I'd suggest that slanting content toward the needs of the various likely "consumers" will be much more successful in the long run. We should also be thinking from the beginning about multimedia--- web-based how-tos and tutorials, video presentations, web_based reference pages, print user manuals. Yes, it's far too ambitious at this stage to pull all this off. But we should PLAN for it from the very beginning and put a solid foundation in place.
Just a quick note about the style manual. It's good that you have one. But I wouldn't put too much emphasis on it too soon. You risk losing sight of the forest for the trees. Our goal is to make it as easy as possible for prospects, adopters, and users to understand how Zotonic meets their respective needs and how to use it to meet those needs with minimal pain, tedium, and learning curve. Spelling, grammar, and whether to it's email, e-mail, or E-mail, at this point, will only bog us down. The time will come for that.
Also, your note re: Cookbook. Some Cookbook items could profitably be folded into other areas of documentation. But, as I see it, the Cookbook concept provides a way for users to share interesting and neat techniques that might not otherwise be known to the community. They're an excellent channel for community participation. Problem now is that they are not well organized by topic. Cookbook items also provide the basis for promotion through the conference, web, and print channels.
Anyway, it's 3:00 a.m. I should be in bed. And these are just a few quick reactions from a crotchety old man.
More when I have more time to think about it.
All the best,
Lloyd
*********************************************
My books:
THE GOSPEL OF ASHES
http://thegospelofashes.com
Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions
FREEIN' PANCHO
http://freeinpancho.com
It takes a community to help a troubled boy find
his way
AYA TAKEO
http://ayatakeo.com
Star-crossed love, war and power in an alternative
universe
Available through Amazon or by request from your
favorite bookstore
Blog:
http://lloydrprentice.com
Facebook:
http://www.facebook.com/pages/The-Gospel-of-Ashes/223711667732007
**********************************************
Andreas Stenius
ll...@writersglen.com
When it comes to software engineering and Erlang system and web development I'm an enthusiastic amateur; can't hold a candle to the best in the Zotonic community.
But my entire professional life has been devoted to getting information out to folks I've never met. For what it's worth, here's how I think about it:
First, I segment my intended audience into stereotypical groups that I do know something about (or think I do, anyway.) This was the intent in my last post when I suggested seven adopter/user cases. Incidentally, let me propose yet one more use case:
Shen the ISP entrepreneur who sees potential value in hosting Zotonic sites.
It's worth time and money to take this step seriously. Michiel's survey was a good step in this direction.
Next, I list the communication channels I have available to reach these groups. In our case the list might look something like this:
- Source code on GitHub
- In-source comments
- Reference pages on the Zotonic website
- Cookbook on the Zotonic website
- Zotonic developer list
- Zotonic user list
- Zotonic Wiki (do we have one? If not, perhaps we should.)
- Web-based tutorials
- YouTube video tutorials
- E-books
- Conference presentations
- Corporate training sessions
- User websites
???
Note that each of these channels has a different FUNCTION, offers different advantages and disadvantages, and serves different audience needs.
The next step is fairly obvious: I set up a matrix with audience segments across the top and channels down the left side. In each cell of the matrix I indicate what this segment of my audience needs to know, theme that encapsulates the essential idea, rhetorical and graphic style that's most likely to draw and hold attention, format that's most likely to meet audience expectations.
Style and format are important considerations: You wouldn't want to read a stock prospectus from the stage of a comedy lounge (unless you're a master of satire.) And, in the U.S. at least, the SEC would come down on you like a ton of bricks if you formatted your stock prospectus like a cartoon.
Keep in mind that everything works against you when you're trying to communicate with other human beings, particularly those you don't know and will never meet: misconceptions about your audience, faulty encoding, channel noise, cultural and language filters, selective attention, perception, and recall, etc., etc. It's a wonder that communication works at all.
So, at this point it's very smart to consider evaluation and feedback. How will you determine if your messages are getting through and having the desired impact? What metrics will you use? What will you do if your initiatives are falling short?
The final phase before actually producing messages is to set priorities based on top-level goals, time, and budget constraints. This done, you're ready to move into action--- creating messages and sending them into the void.
All this may sound rather formidable. But, believe me, it's easier than installing Zotonic and building a non-trivial web site.
Anyway, food for thought--- more once I've scratched a few day-job itches.
All the best,
Lloyd
Andreas Stenius
All this may sound rather formidable. But, believe me, it's easier than installing Zotonic and building a non-trivial web site.
ll...@writersglen.com
The trick is that you don't keep it all in mind at once. It's simply applying systems thinking to the problem. I suspect you do this routinely in the software and hardware realms in your engineering practice.
Could be that the method I'm suggesting is overkill for the task at hand. But I'd argue not for several reasons:
1) It's an excellent way to determine priorities
2) It's an excellent way to allocate scarce time and budget resources
3) It's an excellent way to monitor results and improve outcomes
If you think about it, open-source software documentation is both an aid to adopters AND the best possible marketing tool. Why market open-source software? To build a vibrant, creative community that, in turn, is more likely to help maintain, support, and update the software to the benefit of all users.
Face it, original developers in many cases get tired, bored, or drawn to other challenges. It's up to the community to take on the torch and see that the flame stays lit. But this requires effort in the early stages to construct a solid foundation, culture, and road map for recruiting and building that community.
But no worry. If folks find it useful, I'll continue to flesh out the thinking as it applies to the Zotonic documentation project. With you, Michiel, Marc, Arjan and others on board we should be able to produce world-class documentation for Zotonic without too much burden on any one of us.
All the best,
Lloyd