Skip to content
This repository has been archived by the owner on Dec 7, 2022. It is now read-only.

Latest commit

 

History

History
259 lines (186 loc) · 17.9 KB

README.md

File metadata and controls

259 lines (186 loc) · 17.9 KB
Raw

Logo

LivePerson’s Developer Center and Community

⚠️ The LivePerson Developer Center has been moved to a new, internal-only repository. LivePerson teams can reach out to LivePerson’s DX team for further details.

This site is maintained by LivePerson’s Developer Experience team.

This repository hosts LivePerson’s Developer Center, which can be found at developers.liveperson.com. The site is generated using Jekyll. If you find an issue with the documentation, site structure, meta or anything else, please open an issue and we’ll respond as soon as possible.

Table of contents

  1. 📡 Updating the documentation
  2. 📝 Notes on content and code
  3. 🔨 Building the site locally
  4. 👻 Hiding files
  5. 📋 Template
  6. 📜 Licensing

Updating the documentation

In general, please follow the content and code guidelines, and keep in mind code review best practices.

Every change needs review by a member of LivePerson’s DX team. To get a review, add or mention j9t, itay1313, or lkisoslive as a reviewer. The review request will then be handled directly, or handed over to another DX team member as per DX team needs. The DX team works with an SLA of responding within two work days (which may include asking for more time, depending on PR and capacity). If there’s particular urgency, coordinate with the DX team ahead of time (required for requests that involve non-work days), aim to grant as much time as possible, and share context. If you get no response to a request after two work days, contact the DX team, including a link to your pull request.

All pages on the site correspond to a Markdown file (.md) which can be found inside pages/Documents. To update a file, please branch off of the master branch, edit the file in question, and create a pull request back to the master branch.

Committing changes to the site

Before making any commits, please make sure to read the Updating and creating headers section. There is now a Git precommit hook that ensures you follow the rules on Markdown file creation. This hook will run on every commit and deny commits if they fail the test. The errors will be outputted to ./_scripts/docOutputError.log. If you are adding new content, please make sure you are updating the content in the documentsupdated.yaml file. Our tests will use that YAML file as the source of truth, so make sure your header naming structure matches the documentsupdated.yaml.

File name rules:

  1. All Markdown files must match the pagename that is provided in the headers
  2. Spaces in pagename must be replaced with a “-”
  3. All words are lowercased
  4. All special characters excluding periods and dashes need to be removed from the filename
  5. Periods are replaced by dashes.

Folder name rules:

  1. They must use upper camel case (Pascal case)
  2. All files in the folder, must include a reference in its header to its folder name. This will be in either the documentname, categoryname, or subfoldername (depending on the location of the folder)
  3. All special characters excluding periods, dashes, and “&” need to be removed from Foldername
  4. Periods are replaced with dashes.

Examples:

  • A page name Customizing the Conversational Cloud! should use the file name customizing-the-conversational-cloud.md
  • A document name Add Agent Widgets should use a folder with the name of AddAgentWidgets

The category name is the topmost folder in the sidebar.

How to understand the documentsupdated.yaml file

Example of a normal layout:

- categoryname: Agent Experience
  image: agent-experience-new
  documents:
  - documentname: Add Agent Widgets
    pages:
    - pagename: Add Your Own Widgets to the Agent Workspace
  - documentname: Agent Workspace Widget SDK
    pages:
      - pagename: Overview
      - pagename: Limitations
      - pagename: Methods
      - pagename: Public Model Structure
      - pagename: Public Properties
      - pagename: Best Practices and Troubleshooting
      - pagename: Release Notes
  - documentname: Chat Agent API
    basedomain: https://{domain}/api/account/{accountId}/agentSession
    pages:
    - pagename: Overview
  1. The Top layer 0 in this structure is the category name Agent Experience. Its folder name isAgentExperience.
  2. Add Agent Widgets is a folder in layer 1 with the AgentExperience/AddAgentWidgets path. The Add Agent Widgets folder only contains one page.
  3. AgentExperience/AddAgentWidgets/add-your-own-widgets-to-the-agent-workspace.md is the path of the file, and must list all parent folders, excluding the layer 0 categoryname.
  4. For the above example, the permalink is add-agent-widgets-add-your-own-widgets-to-the-agent-workspace.html.
  5. If you look at the document named Agent Workspace Widget SDK, it is still on level 1 with the AgentExperience/AgentWorkspaceWidgetSDK/ path. The files in the folder are all listed below pages until you get to the last pagename; i.e., the document name Chat Agent API is not a folder located inside Agent Workspace Widget SDK.

Example of a subfolder layout:

- categoryname: Conversational AI
  image: agent-experience
  documents:
  - documentname: Conversational AI
    pages:
      - pagename: Overview
  - documentname: Conversation Builder
    pages:
      - pagename: Tutorials & Guides
        subpages:
          - subpagename: Getting Started
          - subpagename: Using Meta Intents with Conversation Builder
          - subpagename: Implementing a Web View Integration
          - subpagename: Using LivePerson Functions with a Bot
  1. The pagename entry Tutorial & Guides is not a file, but a folder, because it has subpages.
  2. In the Markdown file for Using Meta Intents with Conversation Builder, the pagename must match the subpagename.
  3. The file must include Tutorial & Guides as a subfoldername header since it is at level 2.
  4. The file must include Conversation Builder as a documentname in the header.
  5. The permalink must be conversation-builder-tutorials-guides-using-meta-intents-with-conversation-builder.html.
  6. Notice how the & in the subfoldername is replaced by a dash in the permalink.

Another example:

- categoryname: Getting Started
  image: getting-started
  documents:
  - documentname: Getting Started with your Free Trial Account
  - documentname: Do More with the Conversational Cloud
  - documentname: Customizing the Conversational Cloud
  - documentname: Starting with your Concierge Bot
  - documentname: API Guidelines
    pages:
    - pagename: Accessing LivePerson APIs
    - pagename: Create OAuth 1.0 API keys
    - pagename: OAuth 2.0 Client Credentials
    - pagename: Domain API
    - pagename: Data APIs
    - pagename: API Data Metrics
    - pagename: Engagement Attributes
    - pagename: Analytics Builder Data Metrics
    - pagename: Retry Policy Recommendations
  1. The documentname entry Getting Started with your Free Trial Account does not represent a folder, because it does not contain a pages key.
  2. Since this above file only contains one parent, there should not be a documentname in the file getting-started-with-your-free-trial-account.md.
  3. The pagename for getting-started-with-your-free-trial-account.md must match the documentname in the YAML file Getting Started with your Free Trial Account.

Environments

To update the production and staging environments, create a pull request for master or Staging [sic]. When the pull request gets merged, an automated release cycle will start and publish those changes in around five minutes.

Updating and creating headers

Jekyll uses a front-matter block to arrange and define the various documents on the site. It is the text that appears in between the “---” dashes at the top of each document. It’s technically a YAML snippet, so all YAML formatting and rules apply. Our headers usually include the following key/value pairs:

  • pagename: This is the name of the page that will appear at the top of the document.
  • keywords: This header replaces the keywords found in the respective <meta> element of the page. Leave it empty, as it’s not currently used.
  • sitesection: This key accepts either Documents or Solutions. This designates which part of the site the document is under.
  • categoryname: This is the category to which the document’s API belongs (for example, the “Create Users” method belongs to the Users API which is under Contact Center Management).
  • documentname: This is the API to which the document belongs.
  • subfoldername: This is a sub-folder to which the document belongs, if there is one.
  • permalink: this key defines the link at which the document can be found. The format of this value must be as follows; any other value format will cause the sidebar to malfunction:
    • If the page has a subfoldername value: documentname-subfoldername-pagename. For example: mobile-app-messaging-sdk-for-android-advanced-features-audio-messages.html.
    • If the page does not have a subfoldername value: documentname-pagename. For example: users-api-overview.html.
  • indicator: This key contains a chat or messaging indicator (or both) for a document. It accepts chat, messaging, or both as its values.
  • date_updated: This sets the date of the last substantial update, which includes the date when the page was published. For example: date_updated: 2022/01/30.
  • noindex: Set the value to true, if you want this file to be ignored by search engines.
  • (published: false: This prevents a file from being exported altogether. This can be an option for drafts containing immaterial information close to publication, but should otherwise be avoided.)

Notes on content and code

When contributing to this repository, please observe the following:

Content and punctuation

  • Use American English
  • Prefer active voice
  • Try to use language that’s human and personal
  • Keep it brief
  • Use lists (ordered series in numbered lists, unordered series in bulleted lists)
  • In headings, use sentence case (“This is a heading”)
  • Use an Oxford comma (“one, two, and three”)
  • Use typographically correct quotation marks (“”) (keyboard shortcuts)
  • For dashes, use an em dash, surrounded by spaces (“ — ”)
  • Avoid “here” links
  • Use the singular “they,” whenever a single-person reference is needed
  • In code samples, indent by two spaces
  • For new pages as well as for significant updates, add or update the update date (date_updated)

APIs and SDKs

If you’re adding or deprecating an API or SDK, add it or update its status on the APIs and SDKs overview.

Special formatting

  • You can precede a paragraph with the following to highlight the content:
    • {: .attn-note} — important info to pay attention to
    • {: .attn-alert} — warnings or alerts (anything that indicates a problem)
    • {: .attn-deprecation} — info on features that are discouraged or no longer supported
    • {: .attn-tip} — useful suggestions or ideas
    • {: .attn-info} — complementary or auxiliary info

Code and media

  • For formatting rules not documented here, be consistent and follow the style used by the file(s) being edited (that is, if there is no guidelines on, say, heading markup, use the style used in the files you’re updating)
  • Use Markdown wherever possible (i.e., avoid HTML in Markdown files)
  • Make sure all images have an appropriate replacement text (“alt text”) (this is a forward-looking rule, though one to be applied to existing images when possible)
  • The maximum (view) width for images in this repository is 800 pixels
  • Apart from special Markdown naming rules, use lowercase file names, without spaces

You’ll find that few pages follow all these rules yet. This is subject to change as content and code are being edited.

Content and code guidelines are also subject to change. Please follow LivePerson-internal channels on updates, and review this information occasionally to be aware of the latest. (Note that code reviews may surface previously unknown and undocumented issues. The DX team will work with you to decide whether and how to address such issues.)

Suggestions to these guidelines are welcome.

Building the site locally

Important: This repository currently requires Ruby 2.7.x. Attempts to run the local server on 3.x.x may generate confusing errors.

If you have not done so, install Ruby. Here’s a helpful guide on how to best do that on macOS (you can stop once Ruby is installed, as you don’t need Rails) and on any other system. Another good resource is Jekyll’s installation guide, with the only difference being to have chruby point to a different version of Ruby (like 2.7.6).

Once you have installed Ruby, clone this repository to your machine. Then, navigate to it using Terminal or your preferred command line interface. Follow the steps below to run the site from your machine. If you’re on Windows, don’t forget to run your CLI as an admin.

Install

  1. Run npm install
  2. Run bundle install

Launch

  1. Run npm run serve
  2. Navigate to http://localhost:4000/ (or the port you chose) to access the site

Notes

To use Jekyll’s standard commands, all you need to run in consequent builds of the site is bundle exec jekyll serve. You can add the suffix --incremental to enable incremental building of the site. This saves build times since the regeneration feature is enabled by default (the site rebuilds every time you hit “save”). When --incremental is used, Jekyll won’t rebuild the entire site on every save, only the affected sections. If you’d like the project to automatically open in a new tab, you can add the -o flag to the end of the above command.

Changes that alter site navigation or other changes that change the site as a whole might not show up when using --incremental. If that occurs, kill the build and run bundle exec jekyll serve without the suffix. (This is also true for gulp: You will need to kill your gulp instance and then run the Jekyll command.)

Hiding files

  • Add the files to the Hidden/Hidden folder.
  • Do not include them in the documentsupdated.yaml file.
  • Set noindex to true if you want search engines not to find it.

Any other parameters not documented here, but in the front matter of other files, are deprecated and only present for backwards-compatibility. They should not be used.

Adding new documents to the sidebar

Once you’ve created a new document, you’ll need to have it manually added. We chose a manual process for the sidebar for a few reasons:

  1. It reduces the fragility of the sidebar (the extra, manual step gives us another layer of QA).
  2. It increases the flexibility of the sidebar (we write code once and then maintain a YAML file, making it easier to add options).
  3. It decreases site build times (since the forloops needed to dynamically build a sidebar in a site of our size and complexity are time- and resource-consuming).

The sidebar’s YAML file can be found in the _data folder. It’s called documentsupdated.yaml. You must make sure the name of the file and the pagename in the sidebar correspond; the link the sidebar sends to is auto-generated and must match the permalink in the file’s header (see above). Please make sure the Markdown file created contains its pagename, documentname, categoryname, and permalink in its header. The Markdown file might need more information depending on where it will need to be in the sidebar.

Template

See the _template folder above for a complete template of a simple REST API. Other templates will follow in the future. However, if you have a unique API to document or need further assistance, please reach out to the Developer Experience team before starting to write your document so that we can advise on its structure.

Algolia

Algolia is the tool we use for the search bar. It generates a list of searchable items by indexing it in their dashboard which is then pulled into the search bar within the project

To get the latest data to be added into Algolia simply do a pull request on the production branch (master)

Licensing

All usage of the contents, documentation or code found in this repository is subject to the LivePerson API Terms of Use.