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

Fri Jan 19 02:55:08 UTC 2007

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
+Category:     tasks
 Priority:     normal
-Assigned to:  Anonymous
+Assigned to:  karldied
 Reported by:  vjordan
 Updated by:   karldied
-Status:       active
+Status:       patch (code needs work)

The issue of copying nodes easier is probably better dealt with under a
prior doc issue report at /node/107721 Allow documentation maintainers
to more easily copy nodes [1] which was just listed.

Regarding the topic "Authoring Guidelines," I've been working on a
related issue, /node/110062 Update to Documentation writer's guide [2]. 

Per the suggestion here, the following pertinent sub-sections are
proposed. This proposal is my /perception/ of current guidelines and
what the documentation team leader has stated. Also, my perception is
that it is the most practical process. I put it forth here so the topic
can be discussed in concrete terms. 

... 

*Editing versus adding* pages: Try to edit existing pages rather than
creating new pages. It is better to cover a topic in one location
succinctly, and then reference the topic from related pages. Editing
existing pages rather than creating new ones also preserves links that
reference current pages.

*Version separation*: It's generally better to have one page for all
Drupal versions, rather than separate pages. Separate version pages are
hard to maintain: when an issue is updated on the page for one version,
it's often neglected on the pages for others. Separate handbooks for
each version are impractical due to the amount of work; just one set of
handbooks is difficult to maintain. 
        If versions differ substantially, separate pages are
appropriate. In this case, organize the pages on the same hierarchical
level, but include the version number at the end of the title, such as
"Example topic, v. 5.x"

*Version designation*: Use the "Drupal version" drop-down menu and
select which version the page applies to. If the page applies to more
than one version: 

--Select all the versions which the page applies to

--Information on the page should be listed from newest to oldest
version 

--Mark the sub-sections for each version very clearly 

--If the entire page applies to all versions selected, state so near
the top, so that readers don't wonder what sub-sections apply to their
version 

*Page length*: Longer pages of several screens are acceptable. Use <b>
or <strong> tags to provide sub-topic headings within the page. Very
long pages should list the contents (preferably with links) after the
opening paragraph.  

...
[1] http://drupal.org//node/107721
[2] http://drupal.org//node/110062

karldied

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 [3], 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
[3] 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.

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

Tue, 09 Jan 2007 22:27:30 +0000 : vjordan

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.

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

Wed, 10 Jan 2007 15:02:01 +0000 : pwolanin

For making a 5.x version of various pages, it would be nice to be able
to copy nodes with more facility.
I already sent this as an e-mail to the docs list, but no one seems to
have noticed:

2) Allow doc maintainers to more easily copy nodes:
http://drupal.org/node/106309#comment-186732

infrastructure issue: http://drupal.org/node/107721