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

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