March 9, 2025
+ 12

Add code examples where possible to show users how to work with Couchbase products.

When adding a code example:

Do
  • Make it relevant and applicable to your explanation.

  • Make sure it is a working code sample that the user could use in their own projects.

  • Put the code example in its own separate file.

  • Use the correct format for Code Placeholders.

Don’t
  • Include cultural references.

  • Write the code sample directly inside the .adoc file.

Introducing Examples

Use the following guidelines for adding an example into your documentation:

  • Don’t use directional language to describe where in the text your example is, like "above" or "below." Use "preceding," "previous," or "following."

  • Similar to links, use "see."

  • Use a colon at the end of the phrase you use to introduce your example.

Acceptable Not Acceptable

See the following example:

See the example below.

For an example of how to use a SELECT query, see the following:

The following example shows how to use a SELECT query:

The example below shows how to use a SELECT query.

Adding a Code Example

Antora supports two different methods of inserting smaller blocks of code into a page:

  • Add tags inside code comments to mark the code to include.

  • Choose specific line numbers to include.

Tags

To start a code sample, in the source code file, add tag::<TAG_NAME>[] in a code comment before the lines of code you want to include.

To end a code sample, in the source code file, add end::<TAG_NAME>[] in a code comment following the lines of code you want to include.

For example, the following code has two tags, using and connect:

using System;
// #tag::using[]
using System.Threading.Tasks;
using Couchbase;
// #end::using[]

namespace examples
{
    class StartUsing
    {
        static async Task Main(string[] args)
        {

            // #tag::connect[]
             var cluster = await Cluster.ConnectAsync("couchbase://localhost", "username", "password");
            // #end::connect[]

        ...
        }
    }
}

Line Numbers

To include a specific set of lines of code in your code, use the lines attribute inside your include directive.

For example, the following code would include lines 1-3 of the code file select-true-alias-get-business-days.n1ql:

include::example$javascript-udfs/select-true-alias-get-business-days.n1ql[lines=1..3]

For more information about how to include specific lines of content, see Include Content by Line Ranges in the Asciidoctor Documentation.

Explaining Code Examples

Avoid the built-in code callouts in Antora, where possible.

Use small code examples with the explanation in regular text around the example. Add one-line code comments directly to the code where appropriate to explain the assumptions made in a code example.

Let the user know they should remove the comments to use the code in a production environment.

When you need to explain a larger code example:

  1. Show the full example and provide a brief explanation.

  2. Create a smaller code example out of the larger block of code.

  3. Provide a more detailed explanation for the smaller code example.

  4. Repeat Steps 2 and 3 until you’ve explained the code.