Re: Proposal to manage documentation similar to (or along with) core software.

On 2010-05-15, John Schinnerer <[email protected]> wrote:
> Aloha,
>
> My two cents...
> DRY is great for code.
> Not so great for docs, IMO.
> In current plone documentation, it can be really hard to tell what 
> version(s) a given piece of documentation applies to. And, even when 
> there is a label that says what it applies to, maybe it applies to newer 
> versions and just hasn't been maintained. Or maybe it doesn't and hasn't 
> been maintained. Or there's no indication. Or there is an indication and 
> the indication is just plain wrong. Or it's out of date but there's no 
> way to tell without doing what the doc says and finding out it doesn't 
> work....and so on.

Yes! Thank you for voicing my frustration :-)

> I've had all these experiences at one time or another and if versioned 
> docs will reduce this significantly, I give it +100.

Indeed, I believe they will, simply by making it abundantly clear and
unequivocally obvious what documentation you are reading (because
of the URL of the documentation, e.g. /documentation/4.0. How
much more clear can it get? ;-))

> thanks,
> John S.
>
> On 05/15/2010 10:34 AM, Alex Clark wrote:
>> On 2010-05-13, Israel Saeta Pérez<[email protected]>  wrote:
>>> Hello,
>>>
>>> I've been checking with other people for advice, and almost everyone
>>> involved in documentation thinks that branching manuals for every major
>>> version would result in a lot of duplicated content, since the number of
>>> approaches that change is tiny compared to the number of approaches that
>>> stay the same.
>>
>> Who cares? :-) That statement implies "avoiding duplicated content"
>> means "avoiding confusion" which I don't believe to be true.
>>
>> For me, it comes down to this: I'm confused when I look at
>> http://plone.org/documentation (IOW approaching the project from an
>> outsider looking in) though I do occasionally find something useful via
>> Google.
>>
>> So, if instead I went to http://plone.org/documentation and saw a link to something
>> like this:
>>
>>      http://www.turbogears.org/2.0/docs/
>>
>> I would get a warm/fuzzy. Also, because I happen to be sitting in a TG2 class,
>> and I know the documentation for a newer TG2 release exists, I can go to:
>>
>>      http://www.turbogears.org/2.1/docs/
>>
>> and experience a similar warm/fuzzy. I know this is not an Apples/Apples comparison,
>>   I am just trying to point out that by "throwing your hands up" and invoking
>> "duplicate content" you have just prevented a large percentage of folks from
>> getting that warm/fuzzy. ;-)
>>
>> There is (literally ;-)) no substitute for versioned docs, you either have
>> them or you don't.
>>
>>> I've been updating our current documentation for Plone 4, and I can
>>> swear that most changes (apart from the Upgrade Guide) have involved
>>> just a paragraph or two, where "from Plone 4" has been indicated as
>>> clearly as possible. The exception has been the User Manual, where we
>>> have replaced all screenshots by new Sunburst ones.
>>>
>>> Another exception was when we treated versioning (history) separately
>>> for Plone<3.3 and>3.3, but for this we created separate pages *inside*
>>> the User Manual, and that's all.
>>>
>>> I think we can make versioning to come up organically where needed
>>> rather than forcing it from the start. I mean, if we see that a certain
>>> page contains too many "for Plone X.y, do this instead", create a new
>>> page for this specific version and, if a manual contains too many
>>> version-specific pages, branch off a new one.
>>>
>>> IIRC Anne Botwell suggested time ago to create Kupu styles to
>>> differentiate stuff targeted to specific versions of Plone in a clear,
>>> consistent way along our documentation. Also, we can work to tag docs
>>> with the correct version(s) they apply to, and try to improve the way
>>> this info is presented to the user, so it's always clear to him/her.
>>
>> That's not a bad idea, but I don't think it's any different than
>> "keywords" (i.e. tagging an object as compatible with a particular
>> version).
>>
>>> And, most importantly, *work on actually improving and updating the
>>> documentation*. All this discussion of branching docs for major versions
>>> and all doesn't make any sense at all if we don't get the docs written.
>>> Let's get more work done and discuss less.
>>>
>>> That said, I'm still ok with the proposal to "work towards a release" in
>>> docs. Establishing clear goals and timelines instead of letting
>>> everything exist for months as "ongoing". The work to get our
>>> documentation ready for Plone 3.3 and Plone 4 has turned out to be
>>> really effective, clearly influenced by having a specific goal and timeline.
>>>
>>> For Plone 4 I'm working to get the following done:
>>> - Installation guide.
>>> - Updated videos for the Plone 4 User Manual. The manual itself is
>>> already published, with brand new screenshots. :)
>>
>> If all of this makes folks happy, then of course don't listen to me. But
>> don't forget the other half of my proposal. If you feel a stipend might
>> help you to "help" (read: force) others to do a better job, by all means
>> nag the PF about it.
>>
>>> Sorry for the long email!
>>
>> No prob!
>>
>>>
>>> -- israel
>>>
>>>
>>> ------------------------------------------------------------------------------
>>
>>
>


-- 
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admin


------------------------------------------------------------------------------

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs