[Documentation task] Reorganizing the Patch docs

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

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  add1sun
 Updated by:   sepeck
 Status:       active

We need dww and heine to review changes to these sections.




sepeck



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

Sat, 13 Jan 2007 19:20:58 +0000 : add1sun

This is my first real foray into docs work so let me know if I'm going
about this incorrectly.


I am learning how to do patches and patch review and I find the
Handbook's current docs a bit confusing.  While pages do refer to other
pages, the order in the menu and the way everything is broken out made
it confusing.  I want to propose a little reorg of the existing docs and
then I will also be working on improving some of the pages themselves
(notably Create patches and Submit patches sections) so it is a smoother
ride for newbies like me.  Here is my proposed new ordering, this all
goes under Contributing to Development > Patches:


Background: the basic concept of Diff and Patch
Applying and Reviewing Patches
     HOWTO: Apply patches
        Common problems
        Apply Patches on MacOS X
                FileMerge
        Apply patches in Windows
                Cygwin
                Patch
                UnxUtils
     HOWTO: Set up a test environment to review patches
     Tips for reviewing patches
HOWTO: Submit patches for Drupal
     HOWTO: Create Patches
        Create patches in MacOS X
        Create patches on Windows
                CVS
                Several win diff programs
                Subversion
                TortoiseSVN
                UnxUtils
                WinCVS
                WinMerge


I have grouped Applying and Reviewing since you need to know how to
apply them in order to review them but if folks think it makes more
sense to separate them, that would still flow I think (that is have as
majors: Background, Applying patches, Reviewing patches, Submitting
patches).


Thoughts, comments, rotten tomatoes?




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

Sat, 13 Jan 2007 19:29:49 +0000 : add1sun

Ack, sorry, I really should have a habit of hitting preview first.


let's try that structure one more time:



* Background: basic concept Diff & Patch
* Applying and Reviewing Patches

* HOWTO: Apply patches

* Common problems
* Apply Patches on MacOS X
* Apply patches in Windows

* HOWTO: Set up test env to review
* Tips for reviewing patches

* HOWTO: Submit patches

* HOWTO: Create Patches

* Create patches in MacOS X
* Create patches on Windows





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

Sat, 13 Jan 2007 20:49:04 +0000 : karldied

I expect the Background page would be a welcome addition. To me, the doc
often uses more levels than it needs. Why not "Applying patches" and
"Reviewing patches" be separate and at the same level? Same for "HOWTO:
Submit patches" and "HOWTO: Create patches"? Though it is easy to think
of creating a patch as the necessary step of submitting one, it really
is its own operation. Submit should perhaps say, "Create patch that
meets Drupal standards, then submit an issue this way."




--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/