X

Best Practices from Oracle Development's A‑Team

The OCI Designer Toolkit Documentation Generation

As part of the OCI Designer Toolkit (OKIT) series we will look at the new Markdown Documentation feature introduced in Version 0.16.0 which allows the designer to add Markdown style documentation to the overall model and specific resources thus providing the user with the ability to document their design as they build it and generate Markdown documentation that can be easily converted into a variety of other documentation formats. This blog entry will run through a working example where we will take the existing OKIT CockroachDB Cluster Reference Architecture and add the documentation provided on the OCI Architecture Centre Deploy a highly available CockroachDb cluster page.

Documenting Your Architecture

Although the OKIT visually represents your architecture often you will need to add this to a deliverable document which will necessitate exporting the architecture as an image and then including the resulting image in your documentation. The v0.16.0 release of OKIT now provides an addition "Description" side panel on the right of the canvas where the user can enter a detailed, Markdown, description of the displayed architecture.

As you can see, above, the length of the description is not restricted for our example we have simply taken the description from the OCI Architecture Centre Deploy a highly available CockroachDb cluster page and converted it to simple Markdown. Within the resulting document this will be place at the beginning of the document before the representation of the architecture.

Documenting Resources

Although this in itself can provide the resulting document with a lot of information the export to Markdown will also document each resource and OKIT now provides each resource with a Documentation field where the user can add additional information for the resource.

Generating the Markdown

Once you have finished adding the documentation the architecture can simply be exported to Markdown format from the menu and OKIT will return a zip file containing the Markdown document which can be opened or converted using a number of standard products. The resulting Markdown will consist of the following sections.

Introduction / Overview

This information is taken directly from the Markdown added to the "Description" side panel.

Image

The architecture designed within OKIT will be added to the document to provided a visual representation.

Resource Information

For each resource within the architecture the document will contain its associated description/documentation, a graphic if it is a container and a list of specified properties and associated values. Where the properties are referenced from within the architecture appropriate links are added.

Query

The export to Markdown functionality is also appropriate for the scenario where the use introspects an existing environment and although the resulting document will not, by default, contain user content it will display the visual representation and resource property values.