station 0.0.0 → 0.0.93

data/lib/nexmo_developer/app/views/contribute/guides/tutorials-and-use-cases.md

@@ -0,0 +1,64 @@
+---
+title: Tutorials and Use Cases
+navigation_weight: 5
+---
+
+# Tutorials and Use Cases
+
+Our documentation allows for three different types of "how-to" content:
+
+* Code snippets
+* Tutorials
+* Use cases
+
+If you just want to show a bit of sample code that demonstrates to a reader how to perform a single task, then you need a [code snippet](/contribute/structure/content-types/code-snippets).
+
+If you want to teach a reader how to build something, then you'll need either a **Tutorial** or a **Use Case**. This page will help you decide which of those two formats is right for your content.
+
+## Characteristics of a Tutorial
+
+Tutorials demonstrate how to complete a specific, well-defined task, using a step-by-step format. They nearly always involve a single product.
+
+If all of the following apply, then use the Tutorial format:
+
+* You want to show the user how to create a simple application from scratch using one or more of our SDKs (Tutorials support multiple languages)
+* You will guide them through the process step-by-step
+* You are focusing on a single Vonage API
+* You do not rely heavily on third party APIs or frameworks that you cannot reasonably assume that our readers will be proficient in
+
+### Tutorial examples:
+
+* See [Sending a Facebook message with Failover](/dispatch/tutorials/send-facebook-message-with-failover/introduction) for an example of a single-language tutorial.
+* See [Creating a chat app](/client-sdk/tutorials/in-app-messaging/introduction) for an example of a multi-language tutorial.
+
+
+## Characteristics of a Use Case
+
+While Tutorials provide step-by-step instructions on how to do specific things with one product, Use Cases describe far more complex scenarios, that may use several Vonage API products, and optionally products from other vendors.
+
+Use Cases do not have to provide a step-by-step approach, although sometimes they do. Tutorials always use the step-by-step approach.
+
+If several of the following apply, then consider the Use Case format:
+
+* You have a demo app that you want to show our readers and then break it down to explain how it works
+* You are demonstrating the basis of a "real world" application that someone might actually want to build
+* You might focus on a single Vonage API, or use multiple APIs to build it
+* You rely on third party frameworks or solutions and will link to suitable tutorials and other information on the vendors' sites to help your readers learn more about them beyond what you cover in your use case
+
+### Use Case examples
+
+* [Order Support System](/use-cases/client-sdk-sendinblue-order-confirm) - A Use Case demonstrating Conversation API, Client SDK and SendInBlue API for email. This describes implementing an Order Support System scenario.
+* [Transcribe a recorded call with Amazon Transcribe](/use-cases/trancribe-amazon-api) This use case relies heavily on Amazon Web Services (AWS) to transcribe calls recorded by the Voice API.
+
+
+## Building your Tutorial or Use Case
+
+Once you have decided on the appropriate format, you should first learn how to structure the content of your Tutorial or Use Case:
+
+* [Tutorial structure](/contribute/structure/content-types/tutorials)
+* [Use Case structure](/contribute/structure/content-types/use-cases)
+
+Then, see the appropriate guide to learn how to add your new Tutorial or Use Case to our documentation platform:
+
+* [Creating a Tutorial](/contribute/tutorials-and-use-cases/tutorials)
+* [Creating a Use Case](/contribute/tutorials-and-use-cases/use-cases)

data/lib/nexmo_developer/app/views/contribute/guides/writing-style-guide.md

@@ -0,0 +1,278 @@
+---
+title: Writing Style Guide
+navigation_weight: 2
+---
+
+# Writing Style Guide
+
+These are technical writing guidelines that can be used across all our technical documentation as well as blog posts.
+
+These guidelines are designed to improve clarity and consistency. Some of the benefits of writing in this style are:
+
+* Easier to read and understand.
+* More professional appearance.
+* Easier to translate.
+
+As with most guidelines these are suggestions, not hard and fast rules. Use your best judgement.
+
+## Use inclusive language
+
+Use inclusive language. There are a few specifics mentioned later in this guide, but for a good overview see the [Google guide](https://developers.google.com/style/inclusive-documentation).
+
+## Use present tense
+
+Use present tense. It’s easier to read and translate.
+
+Examples:
+
+* *Future:* Command X will start the server.
+* *Present:* Command X starts the server.
+
+## Use simple language
+
+Use clear, simple, and direct language. Avoid flowery and verbose writing styles.
+
+* Avoid filler words and superfluous adjectives 'really nice feature', 'easily', ‘simple’, 'just', 'please', 'it may be that', 'and that's it'.
+* Avoid subjective phrases. "You can easily...". "It is simple to...".
+
+## Use active voice
+
+Use active voice. In active voice the *Subject* *Verbs* the *Object*. Remember SVO.
+
+Examples:
+
+* *Active voice:* The man ate the apple.
+* *Passive voice:* The apple was eaten by the man.
+* *Active voice:* The NCCO controls the call.
+* *Passive voice:* The call is controlled by the NCCO.
+* *Active voice:* Vonage provides a Messages API.
+* *Passive voice:* A Messages API is provided by Vonage.
+
+Active voice is simpler, more direct, and easier to translate.
+
+## Paragraph breaks
+
+In technical writing, and especially blog posts, you can be more generous with your use of paragraph breaks. Paragraph breaks make the text less overwhelming and easier to read.
+
+## Avoid vague and cautious language
+
+Avoid words like would, should, might and so on.
+
+Example:
+
+* *Avoid:* If you run the Nexmo CLI with no parameters you might see some text, or possibly an error, or something!
+* *Better:* If you run the Nexmo CLI without specifying parameters a help message is displayed.
+
+## Use second person
+
+Use 'you' rather than 'we' when referring to the reader.
+
+Example:
+
+* *Avoid:* We now need to enter an API Key.
+* *Better:* You now need to enter an API Key.
+* *Avoid:* We can now click the button to register our Nexmo Number.
+* *Better:* You can now click the button to register your Nexmo Number.
+* *Best:* Click the button to register your Nexmo Number.
+
+Use Vonage rather than 'we' when referring to the company.
+
+Example:
+
+* *Avoid:* We also provide an SMS API.
+* *Better:* Vonage also provides an SMS API.
+
+## Use American English
+
+The company standard is, as with most software companies, to use American English.
+
+The industry standard dictionary is [Merriam Webster](https://www.merriam-webster.com/).
+
+## Avoid Latin phrases and slang
+
+Latin phrases and abbreviations can sometimes cause confusion. They can also be less convenient to translate.
+
+Examples:
+
+* Use ‘for example’, instead of 'e.g.' and 'that is' rather than 'i.e.'.
+* Don't use words like 'crash', use 'error'. Use 'launch' or 'start' rather than 'fire up'.
+* Bear in mind the reader’s first language may not be English.
+* Mouse is clicked and keyboard is pressed. Avoid terms such as 'hit' when referring to the keyboard.
+
+## Headings
+
+Try to be consistent with capitalization of headings. You can follow these guidelines:
+
+* Use title case (also sometimes known as word case as significant words are capitalized) for top-level topics and sections. For example, 'Code Snippets', 'Guides', 'Markdown Guide', 'Writing Style Guide', 'Installation Guide', 'Messages and Dispatch API'.
+* Use sentence case for topic titles below a top-level section. For example, 'This is the topic title'. The exception to this is if the heading references a top-level section. For example, 'How to use the Getting Started Guide', as Getting Started Guide is a top-level section in this example.
+* Use sentence case for sub-section headings. For example, 'This is a sub-section heading'.
+
+There is no need to capitalize minor words in headings. For example:
+
+* *Avoid:* Messages And Dispatch API.
+* *Better:* Messages and Dispatch API.
+
+Always capitalize words that would normally be capitalized. For example:
+
+* *Avoid:* How to send an sms
+* *Better:* How to send an SMS
+
+The following shows an example of correct heading case:
+
+```
+Getting Started Guide (top-level topic)
+  Overview
+    Concepts
+    How to send an SMS
+    How to use the Installation Guide
+
+Installation Guide
+  Configure your Dashboard
+  Install the Server SDK
+    How to install the Node library
+      Clone the source code from GitHub (sub-section heading, not visible in TOC)
+    How to install the Python library
+      Clone the source code from GitHub (sub-section heading, not visible in TOC)
+  Test the installation
+```
+
+Another example demonstrates correct heading case:
+
+```
+Code Snippets  (main section)
+  Before you begin
+  Connect an inbound call
+  Download a recording
+  Earmuff a call
+  Handle user input with DTMF
+  ...
+```
+
+## Blog article titles
+
+For Vonage developer blog article titles, use title case. Blog article sub-headings should also use title case.
+
+You can refer to [these guidelines](https://www.bkacontent.com/wp-content/uploads/2015/10/Rules-of-AP-Title-Case.png) on using title case.
+
+## Bulleted lists
+
+This is an example of a bulleted list:
+
+* Precede a list with a sentence and a colon.
+* Terminate each sentence in a list with a full stop.
+* Use bulleted lists for lists.
+* Use numbered lists for ordered sequences (procedures, tasks and so on).
+
+Note the following points:
+
+* The list has a piece of text introducing the list followed by a colon.
+* Each item in the list is terminated by a full-stop (period).
+* If each item in the list is a single word a terminating period is not required.
+
+## Codeblocks
+
+When inserting codeblocks for example code in the text:
+
+* Specify the coding language where possible.
+* Break the text before a codeblock with a colon, not a period (which is a hard stop in the mind of the reader, rather than a continuation).
+* There should not be a space before the colon.
+
+## Acronyms
+
+Define acronyms on first use. On subsequent use on a page/section you do not need to redefine the acronym.
+
+## Be explicit
+
+Try to be explicit, that is use precise terms where necessary to improve clarity and avoid ambiguity.
+
+Some examples are given here:
+
+* Using 'Nexmo Number' rather than 'number'.
+* Using 'Nexmo Application' rather than 'application' (where appropriate).
+* Using 'web application' rather than 'application' (where appropriate).
+* Using 'webhook URL' rather than 'endpoint' or 'callback URL'.
+* Using Nexmo Server SDK rather than 'SDK'.
+* Using Nexmo Command Line Interface, or Nexmo CLI, rather than 'command line'.
+
+## Avoid using 'he or she' constructs
+
+Avoid "He or she" (use user/developer/caller as appropriate). Do not replace 'he or she' with 'they'.
+
+Example:
+
+* *Avoid:* The user answers the phone and then he or she hears a voice.
+* *Avoid:* The user answers the phone and then they hear a voice.
+* *Better:* The user answers the phone and then the user hears a voice.
+* *Best:* The user answers the phone and then hears a voice.
+
+## Miscellaneous
+
+Some additional points to bear in mind:
+
+* Explain to the reader *why* they need a particular feature and not just what the feature is.
+* Avoid statements that predict the future, for example, "the next version will have feature X". There are good legal reasons for avoiding predicting the future.
+* Avoid time sensitive information. Specify an exact version where possible, for example '1.1', rather than 'current version' as the current version may change.
+* Avoid using ampersand ('&') instead of 'and', unless you are specifying a programming language operator or similar.
+* "It's" _always_ means 'it is'.
+* Avoid pricing information in technical documentation as it is subject to change, hard to maintain, and could lead to legal issues if wrong.
+
+## Replaceable values
+
+When working with keys, phone numbers, or accounts be clear where values should be replaced by customer-specific values.
+
+Key | Markdown Value | Rendered Value  <small>(if different)</small>
+-- | -- | --
+Timestamp | `2020-01-01 12:00:00` | -
+ISO8601 Timestamp | `2020-01-01T12:00:00.000Z` | -
+Epoch | `1577880000` | -
+HTTP Method | ``[GET]`` or ``[POST]`` | [GET] or [POST]
+HTTP Response | `` `200 OK` `` or §§ `` `404 Not Found` `` | `200 OK` or §§ `404 Not Found`
+Balance | `3.14159` | -
+Latency | `3000` | -
+UUID | `aaaaaaaa-bbbb-cccc-dddd-0123456789ab` | -
+
+## Numbers
+
+When use of a real phone number can't be avoided, for example when listing out the result of `nexmo numbers:list` in the CLI, use the following numbers:
+
+### US Numbers
+
+Human readable format | E.164 format
+-- | --
+`(415) 555-0100` | `14155550100`
+`(415) 555-0101` | `14155550101`
+`(415) 555-0102` | `14155550102`
+`(415) 555-0103` | `14155550103`
+`(415) 555-0104` | `14155550104`
+`(415) 555-0105` | `14155550105`
+
+### GB Numbers
+
+Human readable format | E.164 format
+-- | --
+`020 7946 0000` | `442079460000`
+`020 7946 0001` | `442079460001`
+`020 7946 0002` | `442079460002`
+`020 7946 0003` | `442079460003`
+`020 7946 0004` | `442079460004`
+`020 7946 0005` | `442079460005`
+
+### GB Mobile Numbers
+
+Human readable format | E.164 format
+-- | --
+`07700 900000` | `447700900000`
+`07700 900001` | `447700900001`
+`07700 900002` | `447700900002`
+`07700 900003` | `447700900003`
+`07700 900004` | `447700900004`
+`07700 900005` | `447700900005`
+
+## Examples of writing style guides
+
+Some further examples of writing style guides are:
+
+* [Microsoft Style for Technical Publications](https://books.google.co.uk/books/about/The_Microsoft_Manual_of_Style_for_Techni.html)
+* [Kubernetes](https://kubernetes.io/docs/home/contribute/style-guide/)
+* [.NET](https://github.com/dotnet/docs/blob/master/styleguide/voice-tone.md)
+* [Google's guide on inclusive documentation](https://developers.google.com/style/inclusive-documentation)

data/lib/nexmo_developer/app/views/contribute/overview.md

@@ -0,0 +1,39 @@
+---
+title: Overview
+---
+
+# Contribute
+
+We're always looking at ways to improve our documentation and platform and would love to invite you to contribute your suggestions not only to the content but also the open-source platform that it is built upon.
+
+## [Introduction to contributing](/contribute/guides/introduction)
+
+An introductory guide for first time contributors to understand how and where contributions to Nexmo Developer documentation can be made.
+
+## [Writing Style Guide](/contribute/guides/writing-style-guide)
+
+The Writing Style Guide provides guidance and templates for how Nexmo Developer should be written and structured as well as what we use in place of API credentials and other variables throughout the guides.
+
+## [Markdown Guide](/contribute/guides/markdown-guide)
+
+The Markdown Guide provides examples of how to implement and use all the various components throughout Nexmo Developer from typography and headings to tabbed code examples and syntax highlighting.
+
+## [Structure](/contribute/structure/overview)
+
+The Structure section provides an overview of our documentation content types, which type to use and how our documentation content should be structured.
+
+## [Code Examples](/contribute/guides/code-examples)
+
+The Code Examples page provides examples of how to use tabbed code examples and syntax highlighting.
+
+## [Platform](/contribute/guides/platform)
+
+The platform guide goes into some of the details of how Nexmo Developer works internally including aspects such as Markdown handling, assets and supporting tools.
+
+## [GitHub: Nexmo Developer](https://github.com/nexmo/nexmo-developer)
+
+Nexmo Developer is an open-source platform built using a mix of Ruby on Rails, HTML, JavaScript (ES7 + Webpack), Sass and a custom Markdown parser. All of the tooling and documentation is available for you to contribute to or remix for your own project.
+
+## [Contribution Guidelines](https://github.com/nexmo/nexmo-developer)
+
+The Contribution Guidelines outline the process and steps for reporting bugs or suggesting features as well as the semantics of contributing to our codebase and dealing with pull requests.

data/lib/nexmo_developer/app/views/contribute/structure/content-types/code-snippets.md

@@ -0,0 +1,140 @@
+---
+title: Code Snippets
+navigation_weight: 3
+---
+
+# Code Snippets
+
+Code snippets provide a quick reference to how to achieve a specific single concern task. They are designed to be easily readable and light on content to allow the user to context switch between the documentation and their codebase without too much distraction. Below you'll find a typical structure of how a code snippet should be structured.
+
+**✅ Examples of when a code snippet is appropriate**
+
+- How to send an SMS
+- Making an outbound call
+- Send verification code
+- Get details about a phone number
+- Buy a number
+
+You can see examples of code snippets in the [Voice API docs](/voice/voice-api/code-snippets/before-you-begin).
+
+**❎ Examples of when a code snippet is not appropriate**
+
+- Two factor authentication
+
+    *Although the components of this should be code snippets the subject in itself is too involved for a code snippet.*
+
+## Anatomy of a code snippet
+
+A code snippet is made of many moving parts, so below is a screenshot of an example code snippet, with the various elements labelled. More details on each element is below.
+
+![Screenshot of a sample code snippet](/assets/images/contributing/code-snippet-anatomy.png)
+
+### Introduction
+
+The **introduction** for a code snippet consists of the title, an opening paragraph about the topic, and then a section introducing the example that this block illustrates. All these elements are contained in the [markdown file for the block](#code-snippet-markdown-file).
+
+### Placeholders 
+
+The **placeholder** are also in the [markdown file](#code-snippet-markdown-file), these values are per-block and the same ones should be used by each language-specific code example.
+
+### Tabbed content
+
+The code snippets of the code snippets are available in a variety of programming languages to support developers from different communities. The **tabbed content** contains a tab for each [per-language config file](#language-config-files) available at the path configured in the [markdown file for each code snippet](#code-snippet-markdown-file). If the file exists, then there will be a tab for it.
+
+### Setup steps
+
+The **setup steps** are automatically generated from the information in the [per-language config files](#language-config-files). The renderer (`app/filters/code_snippet_filter.rb`) creates these collapsible sections from the configuration supplied. The filename in the "Write the code" section and the command to "Run your code" are also controlled here.
+
+### Quickstart code snippets
+
+The [source code](#source-code) is actually snippets of **code in the "code-snippets" repos**. These are external repositories that hold full working examples and we use sections of those examples to demonstrate the code. The source repository, file and range of lines to include are all defined in the [per-language config files](#language-config-files) for each code snippet language example.
+
+### Run the code
+
+A user will want to see a **demo** of the code, so this section describes how to interact with or use the main feature of the code snippet. This should be the same for all the languages and is defined in the [markdown file for each code snippet](#code-snippet-markdown-file).
+
+### Further reading
+
+Finally, any additional links and resources may also be added to the [markdown file for each code snippet](#code-snippet-markdown-file). 
+
+## File locations for Code Snippets
+
+### code snippet markdown file
+
+This is the entry point that causes the code snippet to exist in the first place. It's a markdown file in the `code_snippets` directory for the documentation section it applies to, with a path such as `/_documentation/voice/voice-api/code-snippets/my_awesome-block.md`.
+
+It contains some basic front matter include the page title and navigation weight:
+
+```
+---
+title: Quick howto on a simple thing
+navigation_weight: 5
+---
+```
+
+This file has the title, and some opening content about what the code snippet does or what it's for. Most users may have come from another part of the docs, such as a specific guide, but others may have landed here via search and will lack context.
+
+The [placeholders](#placeholders) are also included here in the markdown file for the code snippet itself.
+
+Within the code snippet markdown file, we define a "code snippet" - this is what renders everything inside the tabbed content block.
+
+````
+```code_snippets
+source: '_examples/concepts/sample-code-snippet'
+application:
+  name: 'Example Application'
+```
+````
+
+This block points to the directory that contains the per-language config files for the tabbed content block. The settings here are combined with the per-language config files, so it's possible to set common settings in this section.
+
+The only other sections coming from this file are the ["Try it out"](#run-the-code) and ["Further reading"](#further-reading) ones.
+
+### Language config files
+
+For each of the tabs in the [tabbed content](#tabbed-content) block, the content is controlled entirely by a language-specific yaml file. This yaml file will be in the location specified by the `source` field in the `code_snippets` code sample, and will be named for the language it covers, such as `ruby.yml` or `python.yml`.
+
+The options available in these config files combine to a very consistent output format across the code snippets. Here's an example from one of our voice applications.
+
+```
+---
+title: Java
+language: java
+dependencies:
+    - 'com.nexmo:client:4.3.0'
+code:
+    source: .repos/nexmo/nexmo-java-code-snippets/src/main/java/com/nexmo/quickstart/voice/TransferCall.java
+    from_line: 42
+    to_line: 42
+client:
+    source: .repos/nexmo/nexmo-java-code-snippets/src/main/java/com/nexmo/quickstart/voice/TransferCall.java
+    from_line: 17
+    to_line: 22
+run_command: java-ide
+file_name: TransferCall.java
+unindent: true
+```
+
+These options control everything from the pre-requisites and setup steps, to showing and running the code.  Set as many or as few of these options as you need: only `title`, `language` and `code` are vital.
+
+Field | Description 
+-- | -- 
+`title` | Displayed on the tab, usually the title-cased language name.
+`language` | The language used, usually lowercase language name (NodeJS is spelled "node").
+`application` | Set up the initial application setup instructions:<br />`name`: Specify the name for the application<br />`disable_ngrok`: Don't include the ngrok mention and link in this block<br />`event_url` and `answer_url`: Specify non-standard URLs for the call events <br />`use_existing`: Direct the user to use an existing Nexmo application rather than telling them to create one  Set as many or as few of these options as you need: only `title`, `language` and `code` are vital.
+`dependencies` | If the block needs extra libraries, describe them here in a comma-separated list. This will be transformed into the "Install dependencies" collapsible block.
+`code` | Configuration describing the code snippet to display:<br />`source`: The file where the full working quickstart example is<br />`from_line`: Line to start the snippet from<br />`to_line`: Line to end the code snippet on (or the end of the file if this isn't included).
+`client` | Configuration describing any setup required, such as setting up the appropriate library. See `code` for details.
+`unindent` | If the code samples have leading tabs, remove as many as make the included code not be indented.
+`file_name` | Name of the file that the user should put the example code into, used in the copy on the page and closely related to `run_command.
+`run_command` | How to run the example once the user created it. Probably related to `file_name` but can take a special value of `java-ide` to give more Java-ish instructions.
+
+
+> If the same value for an option applies to every language example, it can be set in the code snippet definition in the overall code snippet markdown file.
+
+### Source Code
+
+The code displayed within the [tabbed examples](#tabbed-content) belongs in external repositories; these are our "Quick Start" repositories on the [Nexmo Community GitHub organisation](https://github.com/nexmo-community). The directory structure follows that of the `_documentation` directory on Nexmo Developer.
+
+The examples on the Quick Start repositories should be self-contained and executable. In the Code Snippets, we only include the section(s) that are directly relevant to the task that the code snippet is intended to illustrate.
+