Documentation Guidelines

Overview

This guide explains the documentation requirements so that you can publish your topics in YaaS, and also provides guidelines to ensure your documentation follows the YaaS Style and Standards.

It is important to follow these requirements and guidelines so that there is consistency throughout all of the documentation. The goal is to have all contributors write in the same way to ensure a uniform flow throughout the website. For example:
Consistency is key.

These basic principals are explained in more detail in this guide, so read on for further information.

Definition of Done

In YaaS, the product is not done until the documentation is done. For instance, if you have a new service, feature, or solution to publish, you also need adequate documentation to release at the same time. This ensures readers fully understand the product and how to use it.

A product documentation review before publication ensures the content meets the requirements and guidelines. Each contributor allows time for a review cycle of the required documentation.

About the Style and Standards

The YaaS Style and Standards topic describes the grammar and word choices that give your documentation that special YaaS flavor and ensures that your content meets the requirements for publication on the Dev Portal. Because the Microsoft Manual of Style - 4th Edition (MMoS) is the selected style guide for the Dev Portal, this page documents only those standards that are applied differently, that the MMoS does not address, or that are specific only to YaaS. Search this page for any term to read about the standard.

Grammar

ItemYaaS StandardExample

active voice vs. passive voice

Use active voice and present tense.

  • Click Save to commit the changes.

articles

Always verify the use of the articles "a", "an", and "the" where appropriate.

  • a service, an API, the Builder

colon (:) vs. semicolon (;)

Use colons and semicolons sparingly. Use the colon ( : ) to introduce a list of things. The items after a colon are not complete sentences by themselves. The semicolon ( ; ) separates two distinct clauses within one sentence. The phrase after a semicolon is a complete sentence.

  • If the sentence needs a colon but does not need a bulleted list, consider rewriting the sentence to avoid using a colon.
  • If the sentence has a semicolon, try to separate it into two different sentences, or find a cleaner way to combine them into one sentence.

See the examples for ways to write the same sentence with and without a colon or semicolon. The preferred method for such a sentence is without a colon or semicolon.

  • I have three brothers: John is my favorite.
  • There are three brothers in the family; John is my favorite.
  • Of my three brothers, John is my favorite.

imperative mood

Use the imperative mood to write instructional documentation such as procedures and tutorials. The imperative mood tells the reader, directly, to do something. Other moods can imply optional behavior when you might not intend to present an action as optional.

For example, in instructions for uploading documents, clicking Upload is not a suggested, optional action. If the document provides instructions for how to upload documents, assume the readers wants to perform that action. Do not use language such as, "If you want to upload a document, you can click Upload" or, "By clicking Upload, you can choose how many documents you want to upload." Instead write, "Click Upload and select one or more documents."

  • Click Run to execute the program.

pronouns

Use the second person and the pronouns "you," "your," and "yours" to speak directly to the reader. Do not use the first person pronouns "we," "us," or "let's."

  • You can save your files in the cloud or on your local machine.

serial commas

Use serial commas.

  • Offices are located in Boulder, Gliwice, and Montreal.

tenses: present, future, and conditional

Use present tense. In technical writing, present tense is easier to read than past or future tense. Simple verbs are easier to read and understand than complex verbs, such as verbs in the progressive or perfect tense.

The more concise and straightforward you can be, the better.

  • The process runs in the background.
  • Enter the information and click OK.
  • If the information does not match, an error message appears.

Preferred Terminology

ItemYaaS StandardExample

a vs. the (for example, a cart vs. the cart)

Use "the cart" when you are talking about an example. Use "a cart" when you are talking about it as a non-specific, hypothetical cart.

  • Use the service to remove an item from a cart. In this tutorial, create a cart item and then delete the item from the cart.

allow vs. enable vs. can

Do not use "enable" to refer to things that a program makes possible for the user if you can use "allow" or "you can" instead.

Use "enable" to refer to active functionality that is available, or being made available, to a user.

Use "allow" only to refer to features such as security that permit or deny some action to a user.

  • With Microsoft Word 2010, you can save files in HTML format.
  • Windows 7 allows a user without an account to log on as a guest.
  • Enable anonymous sign-in to allow users to use the application as guests.

American English vs. British English

The SAP Hybris standard is American English. Do not use British spelling in the documentation.

  • This document contains information about data modeling.
  • The color of the message changes from blue to red if there are errors.
  • The authorization process is completed.

app vs. application

Use "application."

  • You can create a new application with the Builder.

as shown below

Use "as shown in the example" instead of indicating direction, such as "above" or "below", whenever possible. This helps to ensure that there are no issues if the text is modified, rewritten, or reorganized. You can also write "the following" or "the preceding."

  • Send a GET request to the endpoint as shown.
  • In your request, supply the values for the following parameters:
  • In this example, modify the object you created in the preceding tutorial.

back end vs. backend vs. back-end

Per the MMoS, use a more specific term when possible, such as server, operating system, database, or network. However, if you must use this term, use back end, two words, no hyphen, as a noun. Use back-end, hyphenated, as an adjective to modify a noun. Do not use "backend."

  • Set up accounts in your back-end system with command line requests.
  • Configure the application on the back end.

because vs. since

Do not use "since" to mean "because."

  • Do not use "since" to mean "because." This can be confusing to the worldwide audience and can cause mistranslation.
  • Use "because" to refer to a reason.
  • Use "since" to refer to a passage of time.
  • If it is possible to misinterpret the meaning of "since" as referring to a reason, rewrite the sentence.
  • Because I installed the fast modem, I can download messages quickly.
  • Ever since I installed the fast modem, I can download messages very quickly.

by using vs. using

To avoid ambiguity for worldwide audiences, use "by using" instead of "using" by itself, even if the preposition seems unnecessary.

However, in most cases, you can rewrite the sentence more directly, by highlighting the action verb in the sentence. For example, instead of writing "By using the backup utility to schedule regular backups, you can avoid data loss," use the strong verb "schedule", as shown in the example.

  • Schedule regular backups with the backup utility to avoid data loss.

can vs. may vs. might vs. could

  • Use the verb "can" to describe actions or tasks that the user or program is able to do.
  • Use "may" to express possibility, not to imply that the user has permission to do something.
  • Use "might" to connote greater doubt than "may" or to eliminate ambiguity when "may" could be interpreted to imply permission.
  • Do not use "could" when you mean "can." Like "might," "could" conveys a tone of doubt that is best avoided in technical writing. It is all right to use "could" as the past tense of "can" when users cannot mistake its meaning.
  • You can use the /b option to force a black-and-white screen display.
  • You might receive incorrect results when you run a query in SQL.

"Click Add" vs. "Click the Add button."

If the button has a label with text, use the label name without the word "button."

If the button or icon does not have a text label, use a descriptive name with the word "button." Bold the label or icon name in both cases.

  • Click Add.
  • Click the Maximize icon.

data is vs. data are

Use "data is." You can use the word "data" as a singular or plural term, but always use it with a singular verb. That is, always write "data is", or another appropriate verb. Do not use "datum" or "data are."

  • That data shows that 95 percent of the users prefer a graphical interface.
  • The data gathered so far is incomplete.
  • These facts contradict the earlier data.

e-mail vs. email

Use "email" as a noun, not as a verb. For a verb form, use "send" instead. Do not write "e-mail" with a hyphen.

  • Use the service to create an email template.
  • You can send an email using Outlook.

ensure vs. insure vs. assure

In common English usage, "ensure," "insure," and "assure" are interchangeable in many situations. To provide consistency and to improve readability worldwide, use these distinctions:

  • Use "ensure" to mean "to make sure" or "to guarantee."
  • Use "insure" to mean "to provide insurance."
  • Use "assure" to mean "to state positively" or "to make confident."
  • Verify your email address to ensure that you receive a confirmation email.
  • A homeowner's policy helps insure against loss or destruction.
  • I assure you a confirmation email is on its way.

etc. vs. and so forth vs. and so on vs. et al.

Do not use "etc." or "and so forth" or "and so on" or "et al." except in the specific situations listed here. Be specific about what you are describing.

  • Do not use "and so on" except in situations where screen space is limited or as noted later in this topic. This phrase gives no information about the class of items that it represents, and therefore can create ambiguity.
  • Do not use "and so on" to end a phrase that begins with "for example" or "such as." These opening phrases indicate that what follows is not an exhaustive list, so adding "and so on" is superfluous.
  • It is acceptable to use "and so on" to indicate a logical progression where at least two items are already named.
  • Do not use "et al." except in a text reference citation of three or more authors. Use "and others" instead.
  • Body text is most readable in Times New Roman, Palatino, and other serif fonts.
  • Body text is most readable in serif fonts such as Times New Roman and Palatino.
  • ...a, b, c, and so on.

fill in vs. complete

Use "fill in."

  • Fill in the remaining fields and click Save.

id vs. ID

Use "ID," capitalized, as the abbreviation for "identification." "Id," or "id," has a different meaning in English. In YaaS documentation, "id" is only appropriate when you are documenting code, as shown in the second example.

  • Enter your user ID in the provided field.
  • Provide a value for the id parameter.

i.e. vs. e.g. vs. for example

Do not use i.e. or e.g. Use "that is" or "for example" instead. Depending on the context, "such as" may be appropriate, as well.

Do not use "for example" in the middle of a sentence. Instead of "This smartphone has many uses, for example making calls, sending text messages, and taking pictures," provide the information in two sentences: "This smartphone has many uses. For example, it can make calls, send text messages, and take pictures."

  • There are many reasons to visit Colorado. For example, there are 300 days of sunshine per year. You can enjoy a variety of activities in Colorado, such as skiing, hiking, and visiting museums and breweries.

if vs. when vs. whenever vs. whether

To avoid ambiguity:

  • Use "if" to express a condition.
  • Use "whether" to express uncertainty.
  • Use "when" for situations requiring preparation or to denote the passage of time.
  • Try to avoid the word "whenever." You can typically use "when" instead of "whenever."
  • He will get his driver's license if he passes the driving test.
  • I don't know whether he will pass the driving test.
  • He will take his driver's test when he has enough driving experience, which will take a few months.

in vs. into

  • "In" indicates within the limits, bounds, or area of.
  • "Into" generally implies moving to the inside or interior of.
  • A word is in a paragraph, but you move the text into the document.

key-value pairs

Use "key-value pairs." Do not write key/value, key value, or key:value.

  • The Configuration service uses independent key-value pairs to store all configuration information.

kind vs. type

Use "type."

  • There are three types of files in this folder.

login, log in, log on, logon, sign in, and register

SAP Hybris standards use only "sign in," "sign out," and "register."

To refer to creating or ending a user session on a computer or network, the MMoS standard is "log on" or "log off" or "log off from."

  • Verb: "log on" or "log off", two words
  • Noun or adjective: "logon" or "logoff", one word, no hyphen

Do not use "log in," "login," "log onto," "log off of," "log out," "logout," "sign off," or "sign on" unless these terms appear in the user interface.

  • Sign in to the Builder.
  • Sign out of the Builder.
  • Register for an account.

once vs. after vs. when

To avoid ambiguity, especially for the worldwide audience, do not use "once" or "when" as synonyms for "after." For example:

  • Correct: "After you save the document, you can exit the program."
  • Incorrect: "Once you save the document, you can exit the program."
  • When the document is complete, save the file.
  • After you save the file, sign out of the application.

per vs. for each

Use "per" in technical or statistical contexts, but use "for each" in other contexts.

Do not use "per" to mean "by" or "in accordance with." For example:

  • Correct: "Identify your computer by using the procedure in the next section."
  • Incorrect: "Identify your computer per the procedure in the next section."

When in doubt, don't use "per."

  • You can have only one drive letter for each network resource.
  • Allocate enough time for each upgrade.
  • The soil contains 10 parts per million of available potassium.

plugin vs. plug-in

Hyphenate "plug-in."

  • The Maven plug-in is required.

possible vs. can or cannot

Use "can" and "cannot." Do not write "it is possible" or "it is not possible."

  • You cannot enter more than eight characters.
  • You can add more rows to the list.

replace by vs. replace with

Use "replaces" or "replace with." Do not use "replace" as a noun. Instead of "replaced by," use "replace with" or "replaces" in active voice. For example, instead of "Version 1 is replaced by version 2," write "Version 2 replaces version 1."

  • Replace the selected text with the new text.
  • The new value replaces the previous value.

should vs. must vs. have to

While the MMoS advises using "should" only to describe a recommended, but optional, user action, "should" is ambiguous. When you write "should", it is not always clear whether the reader needs to perform an action. If it is recommended to back up files regularly, you can just say "Back up your files regularly." Then explain the potential danger of not backing up files.

  • Use "must" only to describe a user action that is required.
  • Do not use the phrase "have to." Use "must" instead.
  • Do not use "should" to indicate probability. Wherever possible, express certainty. When that is not possible, use "may" or rephrase.
  • Your computer must have at least 128 MB of RAM to run this program.
  • You must have write permissions to make changes to the file.

simply

Do not use the word "simply" in documentation. Instead of "To complete this task, simply click ABC," eliminate the word "simply" and write "To complete this task, click ABC."

  • To exit the screen, click Done.

single sign-on vs. single sign on

Use single sign on (SSO) to refer to authentication that allows a user to sign into multiple applications with one set of credentials. When referring to the act of signing in, write "sign in."

  • The platform has single sign on (SSO) to make it easier to use related applications.

Third-party names and acronyms

Refer to the originator's official documentation for the correct spelling and capitalization of third-party tools such as JavaScript, Enterprise JavaBeans (EJB), and cron.

  • Enterprise JavaBeans (EJB), is a managed, server-side component architecture for modular construction of enterprise applications.

time-out vs. timeout

Use "time-out" as an adjective or noun. Do not hyphenate when using "time out" as a verb.
  • If the system cannot connect, a time-out event occurs.
  • An error response indicates when the connection times out.

topic vs. section in cross-references

Use "section."

  • For more information about creating email templates, see the Email section.

toward vs. towards

Use "toward."

  • Move toward the exits in an orderly fashion.

typically vs. usually

Use "typically."

  • If you use "typically" at the beginning of a sentence, use a comma after, as shown in the example.
  • Do not use a comma before or after "typically" in the middle of a sentence.
  • Avoid using "typically" at the end of a sentence.
  • Typically, the winter is very cold.
  • It does not typically warm up until May.

uppercase vs. upper case

lowercase vs. lower case

Write "uppercase" and "lowercase" as single words.
  • You can use any combination of uppercase and lowercase letters in a password.

upper right corner vs. upper-right corner

Hyphenate directional indicators such as "upper-right" and "lower-left."
  • Click Save in the upper-right corner.

user vs. you

Use "you." YaaS documentation uses "you" extensively. This form is called second person or direct address.

According to the MMoS, second person supports a friendly tone because it connects you with the reader. It also helps avoid passive voice because it focuses the discussion on the reader.

  • After the process is complete, you can refresh the page to see your changes.

username vs. user name

Use "user name" unless referring to an interface element or parameter name that uses the single word form username.

  • Enter your user name and password.
  • In the Username field, type your user name.

utilize vs. use

Write "use." "Utilize", "utilizing", and "utilization" are typically unnecessary alternatives to "use", "using", and "use" or "usage", respectively.

  • Subscribe to the Loyalty package to use the Loyalty Member service features.

via

Do not use "via." Instead, write "through," "in," "using," "with," "by," or another appropriate American English term.

  • Configure your profile with the Settings options.
  • You can also make the request through a command line interface.

We, us, let's, or our

Do not use "we," "us," "let's," or "our." Instead of "We released a new feature for the Email service," write "A new feature is available for the Email service."

  • An issue in the Document service is now resolved.

Voice and Tone

In YaaS, voice and tone standards apply to the different areas of yaas.io. First, it is important to understand the difference between voice and tone, and then follow the guidelines for writing content in the proper tone, depending on the destination for your documentation.

Difference between voice and tone

The difference between voice and tone can be a bit hard to differentiate at first. But think about the sound of your own voice, or a certain phrase that you use often. Those characteristics define your voice. When you address different people, or write documentation for different situations, you still have the same voice, but you might use a different tone. For instance, if you beat a friend in foosball, you might say, "I crushed you!" But if you beat your child at foosball, you might say, "Good game, kid."

Tones in YaaS

There are different tones for the different areas of the yaas.io domain. The following describes the recommended tone to strive for in your documentation, based on its location in YaaS.

Dev Portal

The Dev Portal docs can range from instructional to somewhat conversational, but always with the goal of helping users understand how to use YaaS for practical purposes and, in blogs and release notes, also helping business users understand changes so they can plan according to their business needs. The Dev Portal tone is:

  • Instructional and factual
  • Detailed, with use cases and examples

Example
Use the Cart service to easily configure a retail cart service, for example, on a T-shirt web site. Call the Cart service endpoints to:

  • Create a new cart
  • Add items to a cart
  • Retrieve the details of items within a cart

See the Cart service tutorials for step-by-step instructions and request and response examples for each of these Cart service tasks. See the API Reference for the methods and API endpoints to use for each call.

About the Syntax Guidelines

These are the guidelines for using specific features, syntax, and elements in the Dev Portal and other areas in YaaS. For information on using the HTML or MD syntax itself, see the Syntax section of the Documentation SDK.

Basic Text Formatting

These are the guidelines for basic text formatting, such as when to use bullets or tables. In general, content is easier to read when it is in chunks. Consider breaking up endless paragraphs by using a list or table.

Ordered and unordered lists

As you write about your topic, use lists to create visual clarity within your content, listing items in a category or listing items in a sequence. Use an ordered, or numbered, list for sequential, instructional steps. Unordered lists are appropriate for list items that have no sequential order, such as a list of valid file types. Follow these guidelines for creating a list:

  • Make list content consistent in structure. For example, make all the bullet points sentences, questions, or sentence fragments, but do not mix types.
  • Punctuate bullet points consistently. If they are all sentences, use periods. If they are sentence fragments, do not use periods.
  • Avoid ending bullet points with punctuation such as semicolons or commas.
  • Capitalize the first letter of each bullet point consistently. Capitalize the first letter unless the list items are always lowercased, as with parameters names.
  • Emphasize the beginning of the bullet point to capture the main idea.
  • If readers must perform list items in order, as in a step-by-step procedure, use an ordered list, and maintain the consistency in structure.

Tables

Another effective way to chunk content is to use tables. Use them when content needs comparison, or as a way to provide information mapping. Think of a table as a list, but with optional columns to provide and organize more information than belongs in a list. Make sure tables are not too long or hard to read, causing the reader to scroll a lot. Break up a long table into multiple tables, if possible. For an example, see the Style and Standards tables.

Format-specific elements

The following tables outline when to use bold font and when to use code font:

Use bold font for these items:
ItemsExamples
Parameters
Events
File names
Path names
Scopes
UI Elements
variables		The partial attribute is optional.
The service publishes a password-reset-requested event.
Open the pom.xml file.
Save the file in the \services\repository\ folder.
Use the hybris.profile_graph_view scope to view data in the graph.
Click on Subscribe.
Click Project > {Your Project Name}. Variables are also enclosed in single curly braces.
Use code font for these items:
ItemsExamples
Code examples
Values
Endpoints
Status and error codes
Parameter and value pairs		Verify the installation with the mvn help:system command.
Set the partial attribute to true to perform a partial replacement.
Send a POST request to the /{tenant}/categories/{categoryId}/media/{mediaId}/commit endpoint.
A successful response includes a status code of 200 OK.
To perform a partial replacement, include partial=true in your request.

Dev Portal Elements

The YaaS documentation's Cascading Style Sheet (CSS) and other plug-ins control elements such as note panels and certain headings. These are the guidelines for using these styled elements. For information on using the HTML or MD syntax itself, see the Syntax section of the Documentation SDK.

Headings

Ideally, headings fit onto one line in the generated output, but balance brevity with a heading that adequately describes the main point of the document, section, or topic. Follow these guidelines when writing headings:

  • Write headings within a document in sentence case. For example, Create a product category.
  • In the Dev Portal, use present tense verbs in headings. For example, Add a document type.
  • While gerunds are acceptable in body-level content, DO NOT use gerunds in headings, as in Creating a storefront.
  • Avoid stacked headings, which are headings without body-level content in between. For example, DO NOT use a Heading 3 (H3) to introduce one or more H4s. Instead, add a paragraph after the H3 that describes the main idea of the content in the headings that follow.
Do not use the first and second heading levels because they are reserved in the style sheets for the following uses:
  • Heading 1 displays the name of a service, tool, or other main topic.
  • Heading 2 displays the title of a document or section.
This means that if you use H1 or H2 inside your documents, the heading is too large in comparison to the overall navigation and separation of sections within the documentation. Start your headings with H3, and increase the numbering from there to decrease the heading size.

Partials

If you have content that you can use in multiple places, use partials. For instance, create a partial for your service URL, then use the partial in all your documentation. When your service URL updates to a new version, you only have to update the partial, not every piece of documentation.

Tooltips

You can use partials as tooltips. For example, in an API Glossary document. When you define a glossary term in the template provided, and use that partial in your document, the definition of the term appears when the reader's cursor hovers over the term. For example, YaaS. Use this feature to make it easier for your readers to understand your content, and follow these guidelines:

  • Define terms that the average person is not familiar with, or is unique in your usage.
  • Don't define terms that are commonplace.
  • Use a tooltip on the first instance of the term on a page, not every time the term appears in the document.

For information on reusing content, see the Reuse Content section of the Documentation SDK.

Panels

You can highlight important information such as Note, Warning, Find Out More, and Tip content in special panels with different colors. For information on using the panel HTML or MD syntax, see Panels in the Syntax section of the Documentation SDK.

Use panels sparingly so that they make an impact. Multiple panels within one page view interrupts the content flow. Also, do not use panels as the first content in a document. Always precede panels with body-level text and use the panel to call attention to the preceding text. For example:

Use different colored panels to highlight certain information in your documentation.

Linking

Linking is a great tool to use to incorporate a lot of content into your document with fewer words. That being said, overuse of linking can create "link rot" when links break, and if a page has more links than content, it is not very pleasing to read. Choose carefully when and how to link by using these best practices.

  • Every link has the potential to go bad over time, and the more links you include, the higher the chance that one will break. If something is not central to the subject at hand, is well-known by your audience, or can be found with a simple search, there's no point in linking.
  • For external links, link to the main page of the external website and then describe how to access the destination link. For example, Go to the <a href="www.raml.org">RAML</a> website and click on the download link. Main page URLs are less likely to change.
  • Choose the link text carefully. Don't link entire phrases which become overemphatic. Instead, choose the noun, such as an article or specification within the phrase that helps the reader understand where the navigation leads them. Or use the title of the article or book as the link, but don't include the author and publisher.
  • Link to web pages instead of PDFs whenever possible.
  • Don't include spaces or other characters in the link that require escape characters for translation.
  • Check your links often to make sure they are still operational. There are free online tools to make it easier.
Good examples

For information on using the HTML or MD linking syntax itself, see the Syntax section of the Documentation SDK.

Images and Diagrams

As someone once said, a picture is worth a thousand words. That is true in YaaS documentation as well. Whenever possible, use a diagram, image, or screenshot to convey a lot of information visually. Follow these guidelines when placing a diagram, screenshot, or other image in your content. For information on using the HTML or MD syntax itself, see the Syntax section of the Documentation SDK.

Images and screenshots

Images and screenshots can quickly convey a lot of important information in your documentation. Do not use directional indicators, such as "above" and "below" to refer to images. Instead, include a brief introduction before each image that describes the purpose of the image and any necessary details. Do not overuse images such as including multiple screenshots of the same screen. Either condense them into one screenshot, or crop the images to show different areas. Follow the rest of these guidelines to make or use images, or capture screenshots:

  • Make or capture your images using any tool that outputs high quality images, such as Snagit. The desired image format is SVG (vector), but PNG and JPG (raster) are acceptable.
  • Use an online tool such as TinyPNG to compress images and limit the size of each image to 1MB, or smaller.
  • By default, displayed images are sized automatically. If you want to control the size of the image relative to the screen size, use one of these standard percentages: 100%, 75%, 50%, or 25%.
  • Most images are left-aligned, unless it is a special case, such as images in a table.
  • Do not include the mouse pointer in your screenshots, unless it shows a function related to the content.
  • To highlight certain areas of an image, crop the image, or use SAP Yellow (RGB: 240,171,0 or HEX: #F0AB00) for arrows or boxes around elements with a three point line width.
  • The style sheets add a gray (#88929E) border with padding around your images by default.
  • For multiple screenshots, use your best judgment as to whether you include one introduction, or whether you introduce each screenshot separately.
  • Describe multiple areas using purple round stamps with white numbers. In Snagit, you can create a number in this style and add it to the quick styles menu:

Snagit Editor
Snagit Editor Styles Menu
  • With a clickable image, include a caption or figure title, which appears at the top of the image in the pop-up window.
  • Do not use figure captions unless it is a clickable image. Instead, introduce the image with a sentence, similar to this example:

    See this example for the screenshot highlight, border, color, and clickable image guidelines:
    YaaS Market Persistence package

    • Diagrams

    Diagrams are a good way to show information flows or a configuration of a product's architecture. Use the Diagram editor as described in the Diagrams section of the Documentation SDK.

    For information about the UI design guidelines, see the techné website.

    Release Notes

    Information in release notes must provide readers with everything they need to know to understand the change in the software. A lot of business decisions are made based on the information in release notes. Therefore, always write from the user’s perspective, not the developer’s perspective. The content of release notes answers the following questions:

    • What changed because of this feature or resolved issue?
    • How was the behavior different before this release?
    • Are there changes to the UI?
    • Are there changes to the functionality?
    • Does an error message appear?
    • Was the enhancement based upon customer feedback?

    Prerequisites and requirements

    First, make sure you understand the document metadata, the folder structure, and where to place release notes as described in the Documentation SDK.

    Because the release notes contain critical information and act as an important communication tool, follow these guidelines so that the documentation is informative and consistent. When authoring release notes, follow the Styles and Standards for many agreed-upon standards, including word choices, use of acronyms, and product names.

    Headlines

    A headline is short, but interesting, and summarizes your release notes. Write headlines in sentence case.

    Write about new features

    When writing about new features, write an enticing paragraph instead of a short, bulleted list. This is an opportunity to market the new feature to customers from a business perspective.

    Write about resolved issues

    When writing about resolved issues, don't call them bugs. Use the term resolved issues because it has a more positive tone. A bulleted list of resolved issues is okay, but ensure that the descriptions make sense.

    Bulleted lists

    For ease of reading, use the same sentence structure throughout a bulleted list. For example, the following items match in sentence structure:

    • Feature xyz – This one is really cool.
    • Feature abc – This one is really, really, cool.
      Don't add an entry that doesn't match, such as:
    • Feature JKL: it's not so cool
    Examples

    For examples of well-written release notes, see the Document service's release notes.

    Filename

    The filename for release notes for services and tools is in the format YYYY-MM-DD-ReleaseNotesServiceName.html.md. For example, 2016-02-09-ReleaseNotesEmail.html.md.

    Version changes

    For a new version of an existing service, such as a v2 or v3 release, use the template in this section for your release note, and make sure you include this information:

    • The new version’s benefits and features, including one or more examples of how to use it
    • When the old service version becomes deprecated, and how long users have to migrate
    • How to migrate to the new service version
    • Where to find more information on the new service version, typically a link to the the new version documentation in the Dev Portal

    Release notes template

    To write and publish release notes, copy the template shown in this section to the docu/release_notes directory, and follow the instructions inside the template. The images shown represent a release note for the Email service.

    The first image represents the title box that displays on the Release Notes page and illustrates how the Dev Portal uses the date, headline, service, and official_version metadata:

    Release Note Heading

    The second image represents the actual release note after you click the title box, and illustrates how the Dev Portal uses the previous_version_shutdown_date metadata. This image also illustrates how to use Heading 3 as the first heading, followed by the body text:

    Release Note

    View or download the Release Notes template:


    Template for Services
    ---
    headline: 'headline'
    date: Month dd, yyyy
    previous_version_shutdown_date: Month dd, yyyy
    official_version: 'version'
    ---
    Features <-- Use H3

    Write a paragraph that highlights the main features if this is a new service or product, or describes the new or modified features if it's an update.

    Resolved issues

    List of issues resolved

    - - - - - - - - - - - - - - - - - - - comments below - - - - - - - - - - - - - - - - - - -


    To fill out the metadata:

    • headline: A short, but interesting headline that summarizes your release notes
    • date: The date of the post in the format October 20, 2016
    • previous_version_shutdown_date: The date when the previous version of the service shuts down, in the format May 28, 2016. This information displays in a yellow note panel until two weeks past the shutdown date.
    • official_version: The v version, included in the proxy link
    • The title of the release notes automatically generates. It is a combination of service+official_version.

    Note the following:

    • The date in the filename controls where your release notes display in the news feed, and should match the date metadata.
    • The previous_version_shutdown_date metadata displays, in a yellow note panel, when the previous version shut down or will shut down. This shutdown date pertains to the previous official_version, such as v1. This information displays until two weeks past the shutdown date.
    • Use Heading 3 (h3) for the first heading, whether it's Features or Resolved issues. Do not use anything bigger than Heading 3.
    • If the new feature resulted from a customer request for an enhancement, include this as part of the description in the release note. For example, "The XYZ feature included in this release resulted from customer feedback. It does the following..."


    Services

    This page lists all of the required documents for services. Provide each of these documents before publishing your package so the purpose and use of each service is easy to understand. All of the documentation for services appears in the API Docs section of the Dev Portal. It is a good idea to familiarize yourself with the Service documentation before creating it. For information on how to build and publish documentation, see the Documentation SDK. When writing any documentation for YaaS, including API Documentation, follow the Styles and Standards.

    Multiple versions of documentation

    Because it is required to keep the previous version of a service available for three months after a new version releases, you must also keep the documentation for that version for that same period of time. Use the code in the registry sample file service-sample-simpleWithTwoVersions.json. The code creates a latest link in the URL to the latest version, and a drop-down menu next to the service name in the API documentation.

    For an example of a service with multiple versions, see the Email service.

    RAML file

    YaaS services use the RESTful API Modeling Language (RAML) to describe their own APIs in a natural and intuitive way. Follow the API Guidelines and create consistent and straightforward RAML API definitions.

    The Dev Portal uses the RAML file as the source for the automatic generation of the API Reference section in the API Docs. For a coherent user experience, include up-to-date examples and clear descriptions. Make the explanations concise and move the more extensive content to the Details or Tutorial section. Remember that the YaaS Style and Standards guidelines apply when you document your endpoints and methods in the RAML file:

    • Focus on the user's task and avoid unnecessary words.
    • Use second person, active voice, and present tense.
    • Stick to the preferred terminology and format standards.
    • Use appropriate articles and punctuation.
    For example:
    "Use the /all endpoint to return a list of all tenants for a given client."

    Because the content of the RAML file appears as part of the API Documentation, a review is required for the RAML file descriptions, or any content that displays publicly.

    Expose the Service URL

    Expose the Service URL because it is the key component of your service. The baseUri automatically generates based on the values provided in the registry JSON file for the following attributes:

    • builder_identifier
    • builder_org
    • version

    The values are added together in the following way:

    
https://api.yaas.io/{builder_org}/{builder_identifier}/{version}

    To provide a custom baseUri, add a field called baseUri to the JSON file, and the value from that field displayes in the Dev Portal. For example:

    
"baseUri": "https://api.stage.yaas.io/hybris/tax-avalara/v1"

    The Dev Portal uses the baseURI in the following ways:

    • It appears the top of the service documentation, in the SERVICE URL box.
    • The API Console uses it to perform REST calls on the proper service instances.
    • Partials in the documentation use thebaseURI to always refer to the latest service version's URL.

    Learn more about partials by reading the Reuse Content section.

    Overview document

    The Overview document is concise and briefly describes the purpose and intended use of the service. Use the proper metadata as described in the Metadata section of the Documentation SDK. Make sure to include the following:

    • Describe who might use the service and why.
    • List the key features of the service in bullet points. Provide more in-depth information in the Details section. Do not explain RESTful API basic functions as a feature of the service.
    • Describe how this service relates to other services, and describe any dependencies, including appropriate links to those dependencies.
    • Optionally, list business examples.
    • Optionally, list any prerequisites with a short description and relevant links to tutorials or documentation.

    API Console and API Reference documents

    If you follow the instructions to register your service in the Documentation SDK, the following occurs:

    • The API Console link displays automatically in a yellow button at the top of the API documentation.
    • The API Reference content and navigation node automatically generates. Even though this is automatically generated, check the RAML file to ensure it is up to date with samples and clear descriptions.
    • A link to the API Reference appears at the bottom of each tutorial for more information about error messages, so make sure the RAML file also describes error messages.
    • The RAML file is available at the top of the API documentation for users to copy or download. Make sure to put the displayName:Managing Data description under the root /resource in the RAML file. This display name is then visible instead of the root resource name.

    If your service does not expose its API, set the raml attribute to false in the registry JSON file, and neither the API Console or API Reference displays in the documentation. Also, set the baseUri attribute to Not applicable to display this text instead of the link to the RAML file. See the JSON templates for more details. For an example, see the Profile Enricher documentation.

    If the API Console or API Reference is not available after following the registration instructions, check the following:

    • The baseURI link to the service provided in the Dev Portal registry exists and is up to date with your service version.
    • By default, the Dev Portal collects the first RAML file found in your project and uses it for generation. If you are using more then one RAML file in your project, specify which file to use in the registry.
    • When including hybris traits in your RAML file, use the full URL including the HTTP or HTTPS protocol.

    Events document

    The Events document is required for services that use the PubSub service to broadcast events that other services can consume.

    First, list the topic owner client above the table. This is one per service, such as hybris.authorization for the OAuth2 service. Then, in the table, list the event type, a description, the link to the schema, and a payload example. You do not need to explain how to consume the event.

    The Events template is printed below, or you can download the template:


    - - - - - - - - - - - - - - - - - copy these lines below - - - - - - - - - - - - - - - - -


    ---
    title: 'Events'
    ---

    For more information about events, see the PubSub service documentation.


    The topic owner client is:

    Event | Description | Schema | Payload Example
    ------------|----------|----------|----------|----------
    Event | Description | Schema | Payload Example


    Each event includes the schema key in its metadata section. This allows you to identify the version of the payload that the event contains.

    - - - - - - - - - - - - - - - - - - - comments below - - - - - - - - - - - - - - - - - - -


    To fill out the metadata above:
    title: It must say 'Events'.

    Leave the partials shown in the preceding table as they are. They contain a link to the PubSub documentation and information about the schema key of the event.

    List the topic owner client, such as hybris.authorization.

    The top line in the table shows the column headings. Leave them as is.

    Replace the bottom line in the table with the event type, description, link to the schema, and a payload example:

    • Event type – This is always listed in past tense, such as subscription-created.
    • Description – A short description of your event, such as The OAuth2 authorization provider created and processed the subscription.
    • Schema – A link to the schema, such as subscriptionCreated_v1.
    • Payload Example – Provide an example of the event payload, as shown in the following sample.


    Events

    For more information about consuming these events, see the PubSub documentation.

    The topic owner client is: hybris.authorization

    TypeDescriptionSchemaPayload Example
    subscriptionCreatedThe OAuth2 authorization provider created and processed the subscription.subscriptionCreated_v1
    {"id":"MDF23X45","subscriber":{"id":"testproject","org":"532506aegf6ed545y397589u"},"package":{"id":"3kztl5ruyevu","version":"450a4fb2a16ef916704f8925","provider":{"id":"toad","org":"44d72ad9cb5e48d2d82d04a2"},"includedServices":[{"id":"moqsowxp1v78","name":"product"},{"id":"bgpbokbmzga6","name":"somename"}]},"validFrom":"2015-11-03T12:22:59.569+0000"}

    Each event includes the schema key in its metadata section. This allows you to identify the version of the payload that the event contains.
    If your payload is really long, use the following template.
    `` --- title: 'Events' ---
    For more information about events, see the PubSub service documentation.
    `

    The topic owner client is:

     <table>
 <!-- Header -->
   <tr>
   <th>Event</th>
   <th>Description</th>
   <th>Schema</th>
   <th>Payload Example</th>
  </tr>
 <!-- End of a header -->

 <!-- First row -->
 <tr>
   <td>Your Event Type</td>
   <td>Your Description</td>
   <td>Your Schema 1 Name</td>
   <td>
   <div class="expand-collapse" data-caption="Your Payload Example"> Copy Payload example here </div>
  </td>
</tr>

      <tr>
    <td>Your Event Type 2</td>
    <td>Your Description 2</td>
    <td>Your Schema 2 Name</td>
    <td>
    <div class="expand-collapse" data-caption="Your Payload Example 2"> Copy Payload example 2 here </div>
    </td>
  </tr>
 <!-- End of a second row -->

 </table>

    Each event includes the schema key in its metadata section. This allows you to identify the version of the payload that the event contains.

    ```

    Details document

    The Details documentation contains more in-depth details about the service. Use the proper metadata as described in the Metadata section of the Documentation SDK. The details are listed in a logical order, starting with the architecture, scopes, and limitations of the service.

    • Include a diagram of the service to illustrate the service execution flow, especially for complex services or a mashup.
    • Define scopes for all services. List the information in a table, including the name of the scope and a short description of what the scope does.
    • List any limitations of the service.

    Give more details about the main features listed in the Overview, and any other features not listed. Each feature is described in a separate heading, and more complex details in sub-headings within the feature. Make sure to include the following:

    • Describe the service in detail, including who would use it, when, and why.
    • Include relevant use cases, describing any real world problems the service can solve.
    • Explain any YaaS terms using the glossary feature, and add any relevant links to the tutorials or FAQs.
    • List any considerations, tricks, or workarounds that help users make the most of using the service.

    Tutorials

    Tutorials in your documentation explain and demonstrate in step-by-step fashion how to use the service. Because the website navigation indicates that these documents are tutorials, the titles should be succinct. Do NOT include "How To" in the title.

    The tutorials are targeted at developers with different amounts of experience with YaaS. For that reason, structure the tutorials so that a beginner can follow the most basic steps, and more experienced developers can learn more fine-grained details, such as troubleshooting or more use cases. Be sure to include the following:

    • Title – Give the tutorial a descriptive title, without the words "How To".
    • Introduction – Introduce each tutorial separately, or as a whole. Be sure to explain any common use-case theme, such as a certain store name with certain products for sale. Also, state the objective of the tutorials and any prerequisites.
    • Step-by-step – Include detailed steps in a quick start guide, or create detailed, interactive steps.
    • Request and response examples - If you include a sample request, list optional and required attributes separately in the request body.
    • Errors – At the end of the tutorial, use the errors_global.html.md partial which inserts the wording, "For more information about error codes, see the API Reference."
    • Optional troubleshooting - Besides providing the error codes, give tips on how to troubleshoot a problem after receiving an error.
    • Optional use cases – Show more than one use case to highlight different features.

    Security document

    The Security document is required only for services with data protection requirements that are not supported locally. This document contains all of the details needed to ensure data privacy, which varies from service to service.

    Refer to the documentation for the Document service and the Document Backup service for examples.

    Glossary document

    Use the Glossary to define terms that are specific to each service. The Glossary generates at the bottom of each API document, after the tutorials. A glossary term should be succinct, and no more than a sentence long so that it displays nicely as a tooltip.

    To add a term to the glossary:

    • Create the docu/partials directory if it doesn’t already exist.
    • In the partials directory, create an HTML file in the form, servicename_term.html. For example: avalaratax_avalara.html
    • Use only the metadata provided in the template, and note the spaces after each :.

    By default, a term in the glossary table renders exactly how it is typed in the term metadata. To render the term with an initial capital letter instead, change the lock_case metadata to true. For example:

    term: mixin
    lock_case: false (default) = mixin
    or
    lock_case: true = Mixin

    After creating a partial for the glossary term, you can use it in your documentation with the partial code, as described in the Reuse Content section of the Documentation SDK. For example, if you include <%- @partial('avalaratax_avalara') %> in your document, the result is:Avalara

    Any documents containing partials must have a .eco extension. For example: overview.html.eco or overview.html.md.eco.

    The Glossary template is printed below, or you can download the template:

    - - - - - - - - - - - - - - - - - copy these lines below - - - - - - - - - - - - - - - - -

    ---
    term: The term you want to add to the glossary
    description: A short description of your term
    lock_case: An optional field, to control the case of your term in the glossary. The default setting is false, which renders the case exactly as it is written above. The true setting renders the term with an initial capital, no matter how appears in the partial.
    ---

    - - - - - - - - - - - - - - - - - - - comments below - - - - - - - - - - - - - - - - - - -
    There is no content other than the metadata above.
    or


    ---
    term: mixin
    description: Customizable definition of additional properties for the product. One product can use many mixins, and many products can use one mixin.
    ---

    Solutions

    YaaS is a platform to build any kind of solution, not just APIs or tools. Single cloud solutions are based on one or more YaaS Market packages. They require proper architectural documentation so your subscribers understand which packages implement each piece of functionality. The Solutions documentation also includes details about extensibility, customization, and what functionality the subscriber can unplug and replace with the subscriber's own solutions. The Dev Portal has a dedicated space for Solutions documentation.

    Follow the Styles and Standards for many agreed-upon standards, including word choices, use of acronyms, and the SAP Hybris product names.

    Overview

    In the first document, add a short introduction that explains the nature of your solution and what business value it brings to the reader. Add a list of features that the solution implements.

    Package list

    Add a section that informs the user about the packages and services your solution includes, such as this example shows:

    PackagesServices
    First PackageService A
    Second PackageService A
    Service B

    Details

    This section describes the details of your solution in a logical order. For example, provide a Getting Started Guide, any integration instructions, and add a Troubleshooting section.

    Structure documents in the navigation

    Group documents of the same type and create the left-hand navigation as described in the Documentation SDK.

    Example

    For an example of unique solution documentation, see the SAP Hybris Profile documentation.

    • Send feedback

      If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

    • Get Help

      Use our private help channel. Receive updates over email and contact our specialists directly.

    • hybris Experts

      If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.