Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

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 sminnee authored
Showing with 29 additions and 10 deletions.
  1. +29 −10 docs/en/misc/contributing.md
39 docs/en/misc/contributing.md
View
@@ -120,18 +120,37 @@ Report security issues to [security@silverstripe.com](mailto:security@silverstri
## Writing Documentation
Documentation for a software project is a continued and collaborative effort,
-we encourage everybody to contribute, from simply fixing spelling mistakes, to writing recipes/howtos,
+we encourage everybody to contribute, from simply fixing spelling mistakes, to writing recipes/howtos,
reviewing existing documentation, and translating the whole thing.
+
Modifying documentation requires basic [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) and
-[Markdown](http://daringfireball.net/projects/markdown/)/[SSMarkdown](ss-markdown) knowledge.
-If you have downloaded SilverStripe or a module, chances
-are that you already have the documentation files - they are kept alongside the source code (in the `docs/` subfolder).
-
-In general, you have to "[fork](http://help.github.com/forking/)" the [github.com/silverstripe/sapphire](http://github.com/silverstripe/sapphire)
-and [github.com/silverstripe/silverstripe-cms](http://github.com/silverstripe/silverstripe-cms) repositories
-and send us "[pull requests](http://help.github.com/pull-requests/)".
-Note: Smaller edits can be performed in the github.com web interface on your fork,
-every page view should have an "edit this file" button.
+[Markdown](http://daringfireball.net/projects/markdown/)/[SSMarkdown](ss-markdown) knowledge,
+and a GitHub user account.
+
+### Editing online
+
+The easiest way of making a change the the documentation is to find the appropriate .md
+file in the [github.com/silverstripe/sapphire](https://github.com/silverstripe/sapphire/edit/3.0/docs/) repository
+and press the "edit" button. You will need a GitHub account to do this.
+
+ * After you have made your change, describe it in the "commit summary" and "extended description" fields below, and press "Commit Changes".
+ * 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.
+
+**Coming soon:** each documentation page will have an "edit" link, to make it easier for you to find this feature.
+
+### Editing on your computer
+
+If you prefer to edit the content on your local machine, you can "[fork](http://help.github.com/forking/)"
+the [github.com/silverstripe/sapphire](http://github.com/silverstripe/sapphire)
+and [github.com/silverstripe/silverstripe-cms](http://github.com/silverstripe/silverstripe-cms)
+repositories and send us "[pull requests](http://help.github.com/pull-requests/)". If you have
+downloaded SilverStripe or a module, chances are that you already have these checkouts.
+
+The documentation is kept alongside the source code in the `docs/` subfolder.
+
+**Note:** If you submit a new feature or an API change, we strongly recommend that your patch
+includes updates to the necessary documentation. This helps prevent our documentation from
+getting out of date.
### Repositories
Please sign in to comment.
Something went wrong with that request. Please try again.