Author: gnaylor
Date: Fri Jul 15 18:46:35 2016
New Revision: 1752864
URL: http://svn.apache.org/viewvc?rev=1752864&view=rev
Log:
Change title, add sections, add intro and linking material
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=1752864&r1=1752863&r2=1752864&view=diff
==============================================================================
--- incubator/taverna/site/trunk/content/community/edit.md (original)
+++ incubator/taverna/site/trunk/content/community/edit.md Fri Jul 15 18:46:35
2016
@@ -1,4 +1,4 @@
-Title: Edit Instructions
+Title: Editing the Website
Notice: Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
@@ -16,142 +16,190 @@ Notice: Licensed to the Apache Softwa
specific language governing permissions and limitations
under the License.
-The Apache Taverna website is maintained as a community effort.
+The Apache Taverna website is maintained through a community effort.
No matter your affiliation to the project, please help us improve the website
by
suggesting edits of any of the pages!
-# Overview
+## Overview
-Apache Taverna's webpages are managed by the [Apache
CMS](http://www.apache.org/dev/cmsref.html) system, and
-(if the file extension is `.md`) written in the [Markdown
format](https://www.apache.org/dev/cmsref.html#markdown).
+Apache Taverna's web pages are managed by the [Apache
CMS](http://www.apache.org/dev/cmsref.html) system, and most are written in
[Markdown](https://www.apache.org/dev/cmsref.html#markdown). (These will have a
`.md` file extension.)
-The raw pages are stored in the <a
href="http://svn.apache.org/repos/asf/incubator/taverna/site/";>SVN repository
asf/incubator/taverna/site</a>, but should be edited using one of the methods
below:
+>Edit the web pages using either
+<a href="#github">GitHub pull requests</a>
+or the <a href="#apache-cms">Apache CMS</a>, as described below.
+Please follow the <a href="#editing-tips">editing guidelines</a> when making
changes.
-# Github pull requests
+(Raw pages are stored in the <a
href="http://svn.apache.org/repos/asf/incubator/taverna/site/";>SVN repository
asf/incubator/taverna/site</a>.)
+
+
+<a name=github></a>
+## Github pull requests
The source for the Apache Taverna website is mirrored to the GitHub project
[incubator-taverna-site](https://github.com/apache/incubator-taverna-site/tree/trunk/content),
-where you can navigate to the source for the page you want to edit. *Anyone
with a GitHub account*
+where you can navigate to the source for the page you want to edit.
+
+>*Anyone with a GitHub account*
can suggest an edit to an Apache Taverna page directly in the browser.
-Note that GitHub's rendering of the Markdown is not 100% equivalent to the
resulting HTML
+Note that **GitHub's rendering of the Markdown is not 100% equivalent** to the
resulting HTML
within the Apache CMS. In particular, the `Title:` and `License:` headers at
the top
of every `.md` file will not be rendered as shown on GitHub.
To submit your suggested change, raise a
-[GitHub pull request](https://github.com/apache/incubator-taverna-site/pulls)
-which will send an email on your behalf to the
+[GitHub pull request](https://github.com/apache/incubator-taverna-site/pulls).
+This will send an email on your behalf to the
[dev@taverna mailing list](/community/lists#devtaverna), where
an Apache Taverna committer will review your change before making it live
-on the Apache Taverna website.
+on the website.
Please sign up to [dev@taverna](/community/lists#devtaverna)
to watch for to any follow-up comments about your changes.
+<a name=apache-cms></a>
+## Apache CMS
-
-# Apache CMS
-
-If you are an Apache Taverna **committer**, then use the
+If you are an **Apache Taverna committer**, use the
[Apache CMS](http://www.apache.org/dev/cmsref.html) directly from
[https://cms.apache.org/taverna/](https://cms.apache.org/taverna/) using your
`@apache.org` account as login.
-You can also drag this bookmarklet to your browser toolbar or bookmark
collection,
-which you can click from any Apache Taverna page you want to edit:
-
- * <a
href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))">Edit
in CMS</a>
+Committers can also drag the
+<a
href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))">Edit
in CMS</a>
+ bookmarklet to your browser toolbar or bookmark collection.
+See <a href="#cms-for-committers">CMS usage for committers</a> for how to use
the Apache CMS.
-
-
-## Non-Taverna committers
+### Non-Taverna Apache committers
If you are an existing
[Apache committer](https://people.apache.org/phonebook.html?unix=committers),
but don't have write access to the pages
-(e.g. you are not in the `incubator` group), then your suggested edit will be
sent as
- an suggested patch to the
-[dev@taverna](/community/lists#devtaverna) mailing list,
-which you should subscribe to in order to respond to any feedback.
-
+(e.g. you are not in the `incubator` group), your edit will be sent as a
+ suggested patch to the
+[dev@taverna](/community/lists#devtaverna) mailing list.
+Subscribe to the mailing list to respond to any feedback.
-## Anonymous use of CMS
+### Anonymous use of CMS
-It is possible to log on to the
+>It is possible to log on to the
[CMS without an Apache account](http://www.apache.org/dev/cmsref.html#faq),
by using the username `anonymous` and an empty password.
+
This can be beneficial if you
prefer not to use GitHub, or if you want to suggest larger changes that
involve renames, etc.
-Note that in this case your suggested edit will be sent as an suggested patch
to the
+Note that in this case your edit will be sent as a suggested patch to the
[dev@taverna](/community/lists#devtaverna) mailing list,
which you should subscribe to in order to respond to any feedback.
-
+<a name=cms-for-committers></a>
## CMS usage for committers
+Before editing an Apache Taverna web page, familiarize yourself with the [CMS
information flow](http://www.apache.org/dev/cmsref.html#flow).
+
+>IMPORTANT: *[Update]* the page or directory before you start editing.
Otherwise, you may not be working on the current version.
+
For details, see the [Apache CMS
reference](http://www.apache.org/dev/cmsref.html).
-In short, follow this pattern:
+### Opening the file
+Open the file in the editor using the **Edit in CMS** bookmarklet:
- * `Get taverna Working Copy`
- * Click on `Parent Directory` where you then click `[Update this directory]`
+ * Navigate to the page you want to edit
+ * Click the bookmarklet and log in
+ * Click `[Update]` to refresh the page
+ * Click `[Edit]` to enter the editor
+
+*Or* use the [Apache CMS]((https://cms.apache.org/taverna/):
+
+ * Click `Get taverna Working Copy`
+ * Click on `Parent Directory`, and then click `[Update this directory]`
* `Browse` to the correct folder under `content/`
* `[Edit]` the file(s)
+### Committing and publishing your changes
* 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.
+ ** You forgot the Quick Commit? No problem! Now click `[Commit]` followed by
`Submit`.
+
+ * Click `[View Staging Build]` to see if CMS has built your changes. Usually
+ this is quite quick. Refresh the page, as necessary, to make sure there are
no "Current" or "Pending" jobs before you continue.
+
* Click `[Staging]` to see the result of your change (and anyone else's 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
+<a name=editing-tips></a>
## Editing tips
-Writing tips:
+### Writing tips:
+
+ * **Keep it simple.** Use [Plain
English](https://en.wikipedia.org/wiki/Plain_English).
+
+ * **Focus on the main questions** you imagine will be faced by someone new to
the topic, rather than explaining every possibility.
+
+
+### Linking 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.
+ * **Avoid [click here](http://www.cs.tut.fi/~jkorpela/www/click.html)
links.** Link text should be understandable and flow with the text. Rewrite the
sentence, if needed.
+ * YES: *"Code is generated automatically by the [CodeGenerator](#) class."*
-Linking tips:
+ * NO: *"Code generation is automatic. More information is in [svn](#)."*
- * [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](/community/lists) 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 be 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
+
+ * **Don't duplicate information.** Link to existing pages - but provide
sufficient context.
+
+ * YES: `Contact the [dev@taverna mailing list](/community/lists) for
questions about the Maven plugin.`
+
+ * NO: `Contact the [dev@taverna mailing list](/community/lists).`
+
+
+ * **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 become confusing out of
context.
+
+ * **Don't break existing hyperlinks** to our pages. (They could be linked-to
anywhere on the web.)
+
+ * Keep the URI of a page as much 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. It
doesn't just look nice, this gives us flexibility to later use a folder `page/`
instead of `page.html`.
+
+ * YES: `/introduction/why-use-workflows`
+
+ * NO: `/introduction/why-use-workflows.html`
+
+ * **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:
+### If you are adding a new page:
+
+ * **Use a short, neutral and sensible URI**
+
+ * YES: `community/lists`
+
+ * NO: `the%20taverna%20community/contact-us-2`
+
+ * **Link 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.
- * Make sure the page has a short, neutral and sensible URI
- * e.g. `community/lists` 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/navbar.html)
and in the listing of a higher-level page.
+ * **Include the page in the [navigation menu
bar](https://github.com/apache/incubator-taverna-site/blob/trunk/templates/navbar.html)**
and in the listing of a higher-level page.
