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

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.
I've had all these experiences at one time or another and if versioned 
docs will reduce this significantly, I give it +100.

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
>>
>>
>> ------------------------------------------------------------------------------
>
>

-- 
John Schinnerer - M.A., Whole Systems Design
--------------------------------------------
- Eco-Living -
Whole Systems Design Services
People - Place - Learning - Integration
[email protected]
http://eco-living.net

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

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