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

On 05/10/2010 12:32 PM, Dylan Jay wrote:
> hmm. sorry I think I my proposal was more confusing that it could be.
>
> I'm proposing two separate ways of dealing with versioning for the KB
> and the manuals.
>
> KB: Keep it the same, ie the way PHC does it. Each content type is
> marked with the versions it applies to. But do allow anyone with edit
> access to updating those versions so that the community can take
> responsibility for saying a howto still applies to plone version 4 for
> instance.
>
> Manuals: Create separate copies of every manual on each major plone
> release.
> For example, we move all the current manuals into a folder at
>
> http://plone.org/documentation/manual/plone3
>
> and at the time of the plone4 release we create a new folder at
>
> http://plone.org/documentation/manual/plone4
>
> and start editing those manuals independently from all the older
> plone3 versions.
>
> Pros
> ------
> - Users always know they are reading up to date documentation
> - It's very clear what to do when you want to documentation on and
> older version
> - The manuals will be simpler as we can simply remove things no longer
> relevant to older releases and we won't have to explain that certain
> things only apply to x release.
>
> Cons
> ------
> - More work if there is a correction needed in more than one major
> release. I suspect this doesn't happen often and I think it's ok to
> let old manuals go unfixed in many cases. We can't do everything. Also
> if we go with the sphnix developer manual then backporting
> documentation fixes to multiple branches is actually manageable using
> svn.


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.

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.

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. :)


Sorry for the long email!

-- israel


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