Skip to content
This repository
Browse code

DOC Gave easier instructions for would-be authors

The use of GitHub for documentation isn't ideal in a world full of wikis,
but we do it because it has other substantial advantages. However, we
shouldn't assume that every would-be author is comfortable using pull requests.

This change presents the edit-on-github interaction as the most straightforward
one, suggesting that advanced users may which to check out locally.
  • Loading branch information...
commit 898f9ad3a969ac2e34caf1a602cdc0ab85f62055 1 parent 619ea7c
Sam Minnée authored August 30, 2012

Showing 1 changed file with 29 additions and 10 deletions. Show diff stats Hide diff stats

  1. 39  docs/en/misc/contributing.md
39  docs/en/misc/contributing.md
Source Rendered
@@ -120,18 +120,37 @@ Report security issues to [security@silverstripe.com](mailto:security@silverstri
120 120
 ## Writing Documentation
121 121
 
122 122
 Documentation for a software project is a continued and collaborative effort,
123  
-we encourage everybody to contribute, from simply fixing spelling mistakes, to writing recipes/howtos,
  123
+we encourage everybody to contribute, from simply fixing spelling mistakes, to writing recipes/howtos, 
124 124
 reviewing existing documentation, and translating the whole thing.
  125
+
125 126
 Modifying documentation requires basic [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) and
126  
-[Markdown](http://daringfireball.net/projects/markdown/)/[SSMarkdown](ss-markdown) knowledge. 
127  
-If you have downloaded SilverStripe or a module, chances
128  
-are that you already have the documentation files - they are kept alongside the source code (in the `docs/` subfolder).
129  
-
130  
-In general, you have to "[fork](http://help.github.com/forking/)" the [github.com/silverstripe/sapphire](http://github.com/silverstripe/sapphire)
131  
-and [github.com/silverstripe/silverstripe-cms](http://github.com/silverstripe/silverstripe-cms) repositories
132  
-and send us "[pull requests](http://help.github.com/pull-requests/)". 
133  
-Note: Smaller edits can be performed in the github.com web interface on your fork,
134  
-every page view should have an "edit this file" button.
  127
+[Markdown](http://daringfireball.net/projects/markdown/)/[SSMarkdown](ss-markdown) knowledge,
  128
+and a GitHub user account.
  129
+
  130
+### Editing online
  131
+
  132
+The easiest way of making a change the the documentation is to find the appropriate .md 
  133
+file in the [github.com/silverstripe/sapphire](https://github.com/silverstripe/sapphire/edit/3.0/docs/) repository
  134
+and press the "edit" button.  You will need a GitHub account to do this.
  135
+
  136
+ * After you have made your change, describe it in the "commit summary" and "extended description" fields below, and press "Commit Changes".
  137
+ * After that you will see form to submit a Pull Request.  You should just be able to submit the form, and your changes will be sent to the core team for approval.
  138
+
  139
+**Coming soon:** each documentation page will have an "edit" link, to make it easier for you to find this feature.
  140
+
  141
+### Editing on your computer
  142
+
  143
+If you prefer to edit the content on your local machine, you can "[fork](http://help.github.com/forking/)" 
  144
+the [github.com/silverstripe/sapphire](http://github.com/silverstripe/sapphire)
  145
+and [github.com/silverstripe/silverstripe-cms](http://github.com/silverstripe/silverstripe-cms) 
  146
+repositories and send us "[pull requests](http://help.github.com/pull-requests/)".   If you have 
  147
+downloaded SilverStripe or a module, chances are that you already have these checkouts.
  148
+
  149
+The documentation is kept alongside the source code in the `docs/` subfolder.
  150
+
  151
+**Note:** If you submit a new feature or an API change, we strongly recommend that your patch
  152
+includes updates to the necessary documentation.  This helps prevent our documentation from 
  153
+getting out of date.
135 154
 
136 155
 ### Repositories
137 156
 

0 notes on commit 898f9ad

Please sign in to comment.
Something went wrong with that request. Please try again.