Re: [Plone-docs] If core code is undocumented it's broken (Was: where should developer documentation go?)

[Ricardo N. <ri...@di...>]

Christopher,

If I understand you correctly, it seems you are arguing for better  
written and more relevant documentation.  I don't think anyone here  
would disagree.  I agree that the problem is not all just one of  
organization and navigability.  We have some really good docs.  We  
also have some not so good.  I'm pretty sure the doc team is aware of  
this and are working on it.  And I'm sure they would appreciate any  
specific examples of problems you see.

But that being said, the example you did cite confuses me...
http://plone.org/documentation/tutorial/where-is-what/the-logo/?searchterm=change%20plone%20logo

To my eye this doc doesn't seem too bad.  I think I might have written  
it a little differently -- it's a little too terse; you really  
shouldn't assume that people have read the prior pages in a multipage  
document; the steps required to do something should be an ordered list  
not an unordered list; and perhaps an example should be included --  
but other than that, it's actually not too bad.  If you have  
suggestions on how to improve this doc, I'm sure the doc team would be  
happy to hear it.  But... is the complaint that the steps to change  
the plone logo are a little cumbersome?  I agree.  Simple theming  
changes should be easier.  The current situation is a little like  
needing to take your car to the mechanic just to change the seat  
covers.  But that's not really a documentation issue, it's a code issue.

Ric



On Nov 18, 2008, at 9:15 AM, Warner, Christopher wrote:

> I tend to agree, however you can’t navigate efficiently what isn’t  
> there or if it’s become a tangled mess it needs to be untangled. As  
> a user of Plone, developer, and general advocate of it as the  
> enterprise CMS of choice. It all seems like a tangled mess to me.  
> It’s embarrassing for me to say to people, “Go to plone.org and read  
> X introduction tutorial.”,  because really it’s an exercise in  
> frustration for new comers. Justifying it at work has only been  
> possible because the people in-charge believe I have a slight idea  
> as to what I’m talking about.  How come I can’t say to management,  
> peers, or just a random individual interested in what I’m talking  
> about; Here’s an overview of this Enterprise CMS. These are the  
> things it offers and here is a high level overview of all the pieces  
> and how they fit together.  Here’s a decent manual if you are  
> interested. Here’s a system administrator overview; it’s not a LAMP  
> stack so we need a manual/section for that. Etc etc. It’s  
> intimidating for new users!
>
> It’s sort of like this weekend, my own cousin, who’s a rocket  
> scientist sits in front of my computer. She says, “How do I eject  
> the cdrom?” I say, “Press the eject key.” She pressed it but didn’t  
> hold it down. So it didn’t eject. She then whined about how it  
> doesn’t work, even though she has her own macbook pro she never used  
> a tower before so it seemed foreign. The problem wasn’t that it  
> didn’t work; it was my instruction. When I told her to hold down the  
> eject button; it made perfect sense to her.
>
> So the “Press the eject button” and “Press and hold the eject  
> button”. Made all the difference, summarily that’s what I feel is  
> missing we also now know it takes one rocket scientist to press an  
> eject key. Kidding aside, that extra piece that can make things  
> clear. A mega-doc can always be cut into little more useful chapters  
> or pieces once it’s organized correctly. If we can start with  
> something along the lines of What is the first thing a person may  
> want to do when they’ve installed Plone? Change the logo? Change the  
> theme? Etc. This can lead into more advanced and comprehensively  
> more difficult topics slowly. The developer and documentation team  
> absolutely need to work together for this to happen.
>
> Lets take a look at what I find when I search for “Change plone logo”
> http://plone.org/documentation/tutorial/where-is-what/the-logo/?searchterm=change%20plone%20logo
>
> I’m not debating the validity of the instruction, however I can’t  
> honestly tell someone who’s interested in Plone and wants to change  
> their logo to read this page. Far less the default theme. Its just  
> useless to them. It’s hard to sell this stuff when people can’t  
> understand it and the documentation doesn’t make it easy; for  
> anyone.  I really want to attack this problem head-on because it’s  
> the #1 problem opensource products always have. Zope/Plone get a bad  
> rap because you need to be dedicated and an excellent programmer to  
> get anything done. The world is filled with Drupal and Wordpress and  
> all that because they make it easy, not because it’s better but  
> because it’s accessible. Not everyone is dedicated or excellent at  
> what they do, the world is filled with mediocre; there’s nothing  
> wrong with that but we are all mediocre at something. http://drupal.org/files/getting-started_2.pdf 
>  <- How come we don’t have this? It’s not like we can’t do it..
>
> Yesterday, I had to send out yet another email saying “Plone is  
> great... This maybe hard... Don’t be scared...”. I like hard  
> problems, so for me that may actually get me interested; but  
> everyone else wants to do their job, go home and play some pool. I  
> can understand that.
>
> -- 
> Christopher Warner
> Manager, Content Management Systems
> New York Media | 75 Varick St, 4th Fl
> New York, NY 10013
> phone: 212.508.0542
> cell: 646.334.6780
>
>
>
>
>
>
> On 11/17/08 7:28 PM, "Ricardo Newbery" <ri...@di...> wrote:
>
>>
>>
>>
>> The current documentation situation is much improved from its  
>> previous
>> incarnations and it seems like the doc team is well on the way to
>> improving it still more.  That being said, I agree we still have
>> problems.  It should be easier to find some bits.  It should be  
>> easier
>> to filter out the bits that aren't relevant.  There are too many mini
>> docs of marginal utility that interfere with efficient navigation.
>>
>> IMHO, the problem isn't whether we need to choose between one mega-
>> document to walk through *all* of Plone or a bunch of discrete
>> documents covering specific topics.  Whether we have one doc or many,
>> what we need is an information architecture and navigation that makes
>> it easier to find the bits you need and filter out the bits you  
>> don't.
>>
>> There is nothing intrinsic to maintaining mega-docs that would make
>> them more usable or accurate than maintaining discrete medium-size
>> docs.  There is also nothing intrinsic to maintaining mega-docs that
>> would help encourage and empower contributers more than maintaining
>> discrete medium-size docs.
>>
>> On the other hand, a mega-doc may tend to encourage a single vision  
>> of
>> focus, presentation, and style.  That may be a good thing... or it  
>> may
>> not.  I'm not sure.
>>
>> Perhaps also there is some benefit to organizing documentation by
>> Plone version, or perhaps just make it easier to navigate or filter
>> documentation by Plone version.
>>
>> Ric
>>