svn commit: r939551 - in /websites/staging/taverna/trunk: cgi-bin/ content/ content/community/edit.html

[bu...@apache.org]

Author: buildbot
Date: Mon Feb  9 12:24:22 2015
New Revision: 939551

Log:
Staging update by buildbot for taverna

Modified:
    websites/staging/taverna/trunk/cgi-bin/   (props changed)
    websites/staging/taverna/trunk/content/   (props changed)
    websites/staging/taverna/trunk/content/community/edit.html

Propchange: websites/staging/taverna/trunk/cgi-bin/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Feb  9 12:24:22 2015
@@ -1 +1 @@
-1658372
+1658381

Propchange: websites/staging/taverna/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Feb  9 12:24:22 2015
@@ -1 +1 @@
-1658372
+1658381

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