svn commit: r1658381 - /incubator/taverna/site/trunk/content/community/edit.md

[st...@apache.org]

Author: stain
Date: Mon Feb  9 12:24:18 2015
New Revision: 1658381

URL: http://svn.apache.org/r1658381
Log:
CMS commit to taverna by stain

Modified:
    incubator/taverna/site/trunk/content/community/edit.md

Modified: incubator/taverna/site/trunk/content/community/edit.md
URL: http://svn.apache.org/viewvc/incubator/taverna/site/trunk/content/community/edit.md?rev=1658381&r1=1658380&r2=1658381&view=diff
==============================================================================
--- incubator/taverna/site/trunk/content/community/edit.md (original)
+++ incubator/taverna/site/trunk/content/community/edit.md Mon Feb  9 12:24:18 2015
@@ -100,16 +100,58 @@ For details, see the [Apache CMS referen
 In short, follow this pattern:
 
  * `Get taverna Working Copy`
- * `[Update this directory]`
- * `Browse` to the correct folder
- * `[Edit]` the file
- * Tick `Quick Commit : [ ]` and click `Submit`
- * 
-
-
-If for some reason the edit page does not match the staged or production page, 
-this could be because your version of cms is not up to date with the underlying svn repository.
-Clicking on the [update] or [Update this directory] link, and then update this resource should solve that issue.
-
-
+ * Click on `Parent Directory` where you then click `[Update this directory]`
+ * `Browse` to the correct folder under `content/`
+ * `[Edit]` the file(s)
 
+ * Tick `Quick Commit : [ ]` and click `Submit`
+ ** You forgot the Quick Commit? Now click `[Commit]` followed by `Submit`
+ * Click/Refresh `[View Staging Build]` to see if CMS has built your changes. Usually
+   this is quite quick. there should be no "Current" or "Pending" jobs.
+ * Click `[Staging]` to see the result of your change (and anyone elses at the same time)
+   at the temporary
+   [http://taverna.staging.apache.org/](http://taverna.staging.apache.org/) site. 
+ * If you are happy, go back and click `[Publish]` followed by `[Submit]`, 
+   otherwise keep editing
+
+
+## Editing tips
+
+Writing tips:
+ 
+ * Keep it simple. Use [Plain English](https://en.wikipedia.org/wiki/Plain_English).
+ * Rather than explaining every possibility, focus on the main questions you imagine faced by someone new to the topic.
+
+
+Linking tips:
+
+ * [click here](http://www.cs.tut.fi/~jkorpela/www/click.html) links considered harmful. 
+   * Make link texts that make sense alone, but also flows with the text. Rewrite the sentence if needed.
+   * Example: Instead of 
+      * <del>*"Code generation is automatic. More information is in [svn](#)"*</del>, try: 
+      * *"Code is generated automatically by the [CodeGenerator](#) class"*
+ * Don't duplicate information. Link to existing pages - but provide sufficient context.
+   * Example: *"Contact the [dev@taverna mailing list](/contact) for questions about the Maven plugin"*
+ * Everything is easier with a link. 
+   * Don't just say "You can find more in the documentation" - link to the right place in the documentation.
+   * Deep-links are good, unless the target pages becomes confusing out of context
+ * Don't break existing hyperlinks to our pages (they could linked to anywhere on the web)
+   * Keep the URI of a page as far as possible, or use `.htaccess` redirections.
+   * If a page has been deleted, leave a placeholder page explaining why. 
+     * Remove/update internal links to deleted/moved pages. (<code>svn</code> and <code>grep</code> are your friends)
+ * Start internal links with `/` unless they are part of the same sub-folder.
+ * **Don't** include extensions `.html` or `.cgi` in the internal links
+  *  e.g. 
+link to `/introduction/why-use-workflows` rather than `/introduction/why-use-workflows.html` 
+   * It doesn't just look nice, this gives us flexibility to later use a folder `page/` instead of `page.html`
+ * Don't be afraid to link to source code - more people may appreciate it than you think. Who knows, maybe a patch is around the corner?
+   * Deep-link to source folder/file under the `incubator-taverna-*` project at
+   [GitHub](http://github.com/apache/) 
+
+If you are adding a new page:
+
+ * Make sure the page has a short, neutral and sensible URI
+   * e.g. `community/contact` rather than <del>`the%20taverna%20community/contact-us-2`</del>
+ * Make sure the page is linked from/to relevant existing Apache Taverna pages (not just the hierarchical parent)
+   * For example, if `/code` is describing the source code, and `/community` different ways to contribute, `/code` should link to the `/community` page and vice versa.
+ * Ensure the page is included in the [navigation menu bar](https://github.com/apache/incubator-taverna-site/blob/trunk/templates/default_navbar.html) or in the listing of a higher-level page.
\ No newline at end of file