[GitHub] akrabat commented on a change in pull request #3816: Reorganize actions doc.

[GitBox <gi...@apache.org>]

akrabat commented on a change in pull request #3816: Reorganize actions doc.
URL: https://github.com/apache/incubator-openwhisk/pull/3816#discussion_r198753212
 
 

 ##########
 File path: docs/actions.md
 ##########
 @@ -17,1182 +17,366 @@
 #
 -->
 
-# Creating and invoking OpenWhisk actions
+# OpenWhisk Actions
 
 Actions are stateless functions that run on the OpenWhisk platform. For example, an action can
 be used to detect the faces in an image, respond to a database change, respond to an API call,
 or post a Tweet. In general, an action is invoked in response to an event and produces some
 observable output.
 
-An action may be created from a function programmed using a number of supported languages, or
-from a binary-compatible executable, or even executables packaged as Docker containers.
+An action may be created from a function programmed using a number of [supported languages and runtimes](#languages-and-runtimes),
+or from a binary-compatible executable, or even executables packaged as Docker containers.
 
-_Prerequisite:_ The OpenWhisk CLI [`wsk`](https://github.com/apache/incubator-openwhisk-cli/releases)
-makes it easy to create and invoke actions. Instructions for configuring the CLI are available [here](???).
+While the actual function code will be specific to a language and runtime, the OpenWhisk operations to
+create, invoke and manage an action are the same regardless of the implementation choice.
 
-Click on the language of your choice below to learn how to create and invoke an action using OpenWhisk for
-that language. If your preferred language isn't supported directly, you may find the
-[native binary](#creating-native-actions) or [Docker](#creating-docker-actions) action path more suitable.
-Multiple actions may be composed together to create a longer processing pipeline called a
-[sequence](#creating-action-sequences).
+* The OpenWhisk CLI [`wsk`](https://github.com/apache/incubator-openwhisk-cli/releases)
+makes it easy to create and invoke actions. Instructions for configuring the CLI are available [here](cli.md).
+* You can also use the [REST API](rest_api.md).
 
-* [JavaScript](#creating-and-invoking-javascript-actions)
-* [Swift](#creating-swift-actions)
-* [Python](#creating-python-actions)
-* [Java](#creating-java-actions)
-* [PHP](#creating-php-actions)
-* [Docker](#creating-docker-actions)
-* [Go](#creating-go-actions)
-* [Native binaries](#creating-native-actions)
-
-Each invocation of an action results in an activation record that is identified by a unique
-activation ID. The input to an action and the result of an action are a dictionary of key-value
-pairs, where the key is a string and the value a valid JSON value.
-
-In addition, we recommend that you review the following topics:
+The rest of this document provides a [basic tutorial](#the-basics) for invoking an action, passing parameters to it, and
+inspecting the result. We recommend that you get familiar with the following topics first.
 
 Review comment:
   We can't recommend that you get familiar with the following topics first (i.e. before the basic tutorial) when the first prerequisite topic item is the basic tutorial.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services