[documentation] [Documentation feature] Authoring Guidelines for placing/ organising v4.x and v5 documentation

[vjordan]

Issue status update for 
http://drupal.org/node/107953
Post a follow up: 
http://drupal.org/project/comments/add/107953

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     feature requests
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  vjordan
 Updated by:   vjordan
 Status:       active

If an opensource project can't take a breather to mark births, both
recent and ancient, there'd be even less documentation contributors ;-)


It is likely to be important to keep 4.7 documentation for a fair while
after the v5 release. There's going to be a reasonably big v4.x install
base which would appreciate preserving the v4.7 documentation.


Maybe it's possible to retain 4.x (maybe just 4.7?) pages intact and
produce a v5 documentation layer. Where the v4.x information is accurate
for v5 maybe the v5 layer could connect to those pages. Where new
information is required for v5 then link to new pages. I know little
about how the book module works so I couldn't even guess if this is
feasible.


Come to that, I don't know a whole lot about the extent of the v5
changes. If they're not extensive the documentation issues might be much
less significant than I'm guessing them to be. And possible the guidance
could be simple too.




vjordan



Previous comments:
------------------------------------------------------------------------

Tue, 09 Jan 2007 10:49:32 +0000 : vjordan

I have not been able to find guidelines on how to structure
documentation for v4.x and v5. If this guidance is available great, and
maybe you can point me to it? If not I'm making this feature request.


It will be useful to develop guidance, possibly in the  authoring
guidelines [1], on how to document features and changes for major
releases. In particular this guidance would be very useful as V5 starts
to get deployed and more documentation is created with that release in
mind. Well thought-out guidance could help keep the documentation useful
for readers as they use the new release.


Possible guidance might be one of:



* existing content pages are updated with a "5.x" section to explain
differences between v5 and v4.7.
* a new page tagged "5.x" should be created for all pages that have v5
specific content.
* all v5 pages should be placed in a whole new v5 handbook (well, maybe
that's not realistic).

It would be useful to link to, with a view to consolidating, the
discussions regarding how to structure the handbooks to make it easier
for readers to get to v4.x or v5 documents. This feature is likely to be
more in need as people begin to deploy v5.


Related posts:
Feature request on making documentation version-specific -
http://drupal.org/node/105356
One example of the 4.x vs 5.x differences and questions about how to
present - http://drupal.org/node/103915
[1] http://drupal.org/about/authoring




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

Tue, 09 Jan 2007 21:01:40 +0000 : sepeck

In the past we've updated pages to be valid for the current latest
release.  Maintaining multiple versions docs has not been feasible due
to a lack of volunteers.  I will look at the guidelines again.


You will have to excuse the delay on the mail list and mark it down to
the holidays, a new baby birth and one of the documentation teams major
contributors being sick for the last few months.