Zotonic Documentation - Zotonic developers

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion Zotonic Documentation
Received-SPF: pass (google.com: domain of andreas.sten...@gmail.com designates 209.85.212.173 as permitted sender) client-ip=209.85.212.173;
MIME-Version: 1.0
Sender: andreas.sten...@gmail.com
In-Reply-To: <1349334419.015527...@apps.rackspace.com>
References: <1349334419.015527...@apps.rackspace.com>
Date: Thu, 4 Oct 2012 09:16:06 +0200
Message-ID: <CABCxKrd-j0U_+xvaS2OkaTfD=oSUG_EQyS55gG6fGe1x02X...@mail.gmail.com>
Subject: Re: [Zotonic-Dev] Zotonic Documentation
From: Andreas Stenius <andreas.sten...@astekk.se>
To: zotonic-developers@googlegroups.com
Content-Type: multipart/alternative; boundary=f46d043c7dd656341704cb368772

--f46d043c7dd656341704cb368772
Content-Type: text/plain; charset=ISO-8859-1

Hi Lloyd,

Despite the late hour, you deliver enlightening and inspiring insights,
that are invaluable input for our success with Zotonic.
Thank you very much for that.

Looking forward to a rewarding collaboration that should bring top class
documentation for a top class project :)

//Andreas

2012/10/4 <ll...@writersglen.com>

> Hi Michiel,
>
> 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
>
> **********************************************
>
>

--f46d043c7dd656341704cb368772
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

Hi Lloyd,<div><br></div><div>Despite the late hour, you deliver enlightenin=
g and inspiring insights, that are invaluable input for our success with Zo=
tonic.</div><div>Thank you very much for that.</div><div><br></div><div>
Looking forward to a rewarding collaboration that should bring top class do=
cumentation for a top class project :)</div><div><br></div><div>//Andreas</=
div><div><br><div class=3D"gmail_quote">2012/10/4  <span dir=3D"ltr">&lt;<a=
 href=3D"mailto:ll...@writersglen.com" target=3D"_blank">lloyd@writersglen.=
com</a>&gt;</span><br>
<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
x #ccc solid;padding-left:1ex">Hi Michiel,<br>
<br>
I&#39;m taking the liberty of responding to your outline through the Zotoni=
c 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 mad=
e 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, t=
hen the effort WILL fail.<br>

<br>
I haven&#39;t had a chance yet to reflect deeply on the content and structu=
re of the outline. But, quick read-over, it seems to cover most of the esse=
ntial areas. But I have some concerns.<br>
<br>
First, I think much more effort needs to go into parsing the content across=
 key audience segments. We&#39;re all so busy with our lives that when face=
d with a project or task we want to get to the nitty-gritty as fast as poss=
ible and see immediate, if not sooner, results.<br>

<br>
So let me propose seven adopter/user cases:<br>
<br>
1) Sarah the Marketing Manager<br>
<br>
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.<br>
<br>
2) Jess the Web Developer<br>
<br>
He&#39;s in business to make money. He&#39;s discovered the hard-way that c=
lients are increasingly reluctant to pay for the long and tedious hours tha=
t quality web development entails. He needs to train his people.<br>
<br>
3) Bogart the Graphic Designer<br>
<br>
Jess needs to bring Bogart on-board to successfully adopt Zotonic as his fi=
rm&#39;s principal platform.<br>
<br>
4) Erica the Product Manager<br>
<br>
Erica has to enter product descriptions into the company&#39;s CMS as fast =
and accurately as possible. She also maintains a blog for technical users o=
f her company&#39;s products.<br>
<br>
5) Walter the IT guy<br>
<br>
Sarah needs Walter&#39;s buy-in to sell Zotonic to her boss. Walter needs t=
o install and maintain this puppy across a global network. He&#39;s a Micro=
soft guy so suspicious from the get-go.<br>
<br>
6) Yurii the Erlang Guru<br>
<br>
He wants to blow the socks off the Erlang community with wicked new Zotonic=
 features and capabilities.<br>
<br>
7) Lloyd the Indie Publisher. He can&#39;t afford professional web consulta=
nts. But he needs to develop book sites, blogs, and management tools and ca=
n&#39;t spend much time doing it.<br>
<br>
Now, given these seven prospective &quot;customers,&quot; how do we parse t=
he content in the outline to deliver just what each needs to know when they=
 need to know it in the clearest most engaging way?<br>
<br>
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=
&#39;d suggest that slanting content toward the needs of the various likely=
 &quot;consumers&quot; will be much more successful in the long run. We sho=
uld also be thinking from the beginning about multimedia--- web-based how-t=
os and tutorials, video presentations, web_based reference pages, print use=
r manuals. Yes, it&#39;s far too ambitious at this stage to pull all this o=
ff. But we should PLAN for it from the very beginning and put a solid found=
ation in place.<br>

<br>
Just a quick note about the style manual. It&#39;s good that you have one. =
But I wouldn&#39;t put too much emphasis on it too soon. You risk losing si=
ght 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 r=
espective needs and how to use it to meet those needs with minimal pain, te=
dium, and learning curve. Spelling, grammar, and whether to it&#39;s email,=
 e-mail, or E-mail, at this point, will only bog us down. The time will com=
e for that.<br>

<br>
Also, your note re: Cookbook. Some Cookbook items could profitably be folde=
d 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 mig=
ht not otherwise be known to the community. They&#39;re an excellent channe=
l for community participation. Problem now is that they are not well organi=
zed by topic. Cookbook items also provide the basis for promotion through t=
he conference, web, and print channels.<br>

<br>
Anyway, it&#39;s 3:00 a.m. I should be in bed. And these are just a few qui=
ck reactions from a crotchety old man.<br>
<br>
More when I have more time to think about it.<br>
<br>
All the best,<br>
<br>
Lloyd<br>
<br>
<br>
*********************************************<br>
My books:<br>
<br>
THE GOSPEL OF ASHES<br>
<a href=3D"http://thegospelofashes.com" target=3D"_blank">http://thegospelo=
fashes.com</a><br>
<br>
Strength is not enough. Do they have the courage<br>
and the cunning? Can they survive long enough to<br>
save the lives of millions<br>
<br>
FREEIN&#39; PANCHO<br>
<a href=3D"http://freeinpancho.com" target=3D"_blank">http://freeinpancho.c=
om</a><br>
<br>
It takes a community to help a troubled boy find<br>
his way<br>
<br>
AYA TAKEO<br>
<a href=3D"http://ayatakeo.com" target=3D"_blank">http://ayatakeo.com</a><b=
r>
<br>
Star-crossed love, war and power in an alternative<br>
universe<br>
<br>
Available through Amazon or by request from your<br>
favorite bookstore<br>
<br>
Blog:<br>
<a href=3D"http://lloydrprentice.com" target=3D"_blank">http://lloydrprenti=
ce.com</a><br>
<br>
Facebook:<br>
<a href=3D"http://www.facebook.com/pages/The-Gospel-of-Ashes/22371166773200=
7" target=3D"_blank">http://www.facebook.com/pages/The-Gospel-of-Ashes/2237=
11667732007</a><br>
<br>
**********************************************<br>
<br>
</blockquote></div><br></div>

--f46d043c7dd656341704cb368772--
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
