Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

Documentation is organized by audience and purpose. The top-level sections are:

Introduction

Introduction to DDF as a product and notes on documentation conventions.

Core Concepts

High-level, non-technical overview of the primary functions and capabilities of DDF.

Managing

Specific "How-to" sections written for the people who will be maintaining instances of DDF. This section is further sub-divided into:

  • Installing: Setting up a new instance from start to finish
  • Configuring: Setting or updating the settings for an instance. Includes security and hardening instructions.
    • from the Admin Console
    • from the Command Line
    • by editing Configuration files
    • by exporting an existing configuration and importing into the new one
  • Quickstart: getting a test/evaluation instance started quickly.
  • Running
    • Starting
      • from script
      • as a service
    • Monitoring: system health and metrics
    • Data Management:
      • Ingesting
      • Maintaining data integrity
  • Using:
    • Walkthroughs of UIs, Landing page.

Integrating

External APIs used by Integrators to communicate with DDF

    • Data and Metadata
    • Endpoints
    • Eventing
    • Sources
    • Security Services


Developing

Details of Internal interfaces needed to extend functionality of existing components, or create new implementations.

  • System Data Flow
  • Catalog Framework API
  • Developing Sources
  • Transformers
  • Plugins
  • Operations
  • Resources
  • Queries
  • Security Framework
  • Metrics
  • Action Framework
  • Migration API
  • Application Service API
  • General Development Guidelines

Appendices

Reference sections to be linked to by the other sections:

  • Application Reference
  • Application Whitelists
  • All File Formats Supported
  • DDF Dependency List




Organization

Documentation is organized by audience and purpose. The top-level sections are:

Introduction

Introduction to DDF as a product and notes on documentation conventions.

Core Concepts

High-level, non-technical overview of the primary functions and capabilities of DDF.

Managing

Specific "How-to" sections written for the people who will be maintaining instances of DDF. This section is further sub-divided into:

  • Installing: Setting up a new instance from start to finish
  • Configuring: Setting or updating the settings for an instance. Includes security and hardening instructions.
    • from the Admin Console
    • from the Command Line
    • by editing Configuration files
    • by exporting an existing configuration and importing into the new one
  • Quickstart: getting a test/evaluation instance started quickly.
  • Running
    • Starting
      • from script
      • as a service
    • Monitoring: system health and metrics
    • Data Management:
      • Ingesting
      • Maintaining data integrity
  • Using:
    • Walkthroughs of UIs, Landing page.

Integrating

External APIs used by Integrators to communicate with DDF

    • Data and Metadata
    • Endpoints
    • Eventing
    • Sources
    • Security Services


Developing

Details of Internal interfaces needed to extend functionality of existing components, or create new implementations.

  • System Data Flow
  • Catalog Framework API
  • Developing Sources
  • Transformers
  • Plugins
  • Operations
  • Resources
  • Queries
  • Security Framework
  • Metrics
  • Action Framework
  • Migration API
  • Application Service API
  • General Development Guidelines

Appendices

Reference sections to be linked to by the other sections:

  • Application Reference
  • Application Whitelists
  • All File Formats Supported
  • DDF Dependency List




.ftl Files

These files are the freemarker templates used by jbake to generate the finished documentation module.

.adoc Files

Content is maintained in individual adoc files by topic and is contained in the src/main/resources/content . Freemarker templates will include and organize content base on header info with each partial file. The file documentation.adoc is an empty content file that receives the content from all of the templates and is converted to the documentation.html and documentation.pdf finish product files. The partial content files are grouped into

To ensure compatibility with Windows environments, limit subdirectories to 20 characters and adoc files to 35 characters (30 + .adoc extension).

`_<component>-template.adoc` Files

Generic templates for the minimum documentation to be provided when creating new components. These files are not meant to ever be included, but used as baseline when new components are added and need to be documented.

`config.adoc`

A special file containing asciidoctor configuration settings and variable definitions. Currently only one config is used, but others could be added for special use cases.


ganization

An Omnibus of the documentation is compiled from system-wide documentation and all application data. Builds are configured to build and deploy html and pdf versions of all documentation.

All content is actually contained in files .adoc files that follow a naming convention ending in "contents" (`mancontents.adoc`, for example). To keep these partial files from rendering, they are placed in directories named with a leading underscore (`_contents`). These files are "included" by asciidoctor into the proper section of the documentation. 

Section Titles and Headings

To keep the outline of the documentation consistent, headers should be used according to the following guidelines.

= This creates an <h1> heading. Asciidoctor only allows one instance per document, for the title
== <h2> reserved for Application headings
=== <h3> this level shows up on the Table of Contents sidebar, so should be used sparingly, for major sections
==== <h4> This heading will (and those above it) will create a section anchor that can be directly linked, but will not display on the table of contents. 
===== <h5> 
====== <h6>

Headers should also not be used without a title as multiple equal signs can also start a callout block that can cause rendering to break.

Content Templates

The documentation is segmented by intended audience. 

Core Concepts

This section consists of high-level, non-technical overviews of the main features of the project.

Managing

The managing sections are intended for system administrators installing and/or maintaining an installation. This section should primarily focus on how-to tasks and explaining the various configuration options.

Sections to include:

  • Prerequisites (other applications that this app depends on)
  • Installation instructions  (including whether app is installed by default)
  • Configuration instructions (including calling out any configurations that must be changed from the default)

Integrating

The integrating sections are intended for integrators connecting programmatically to the project from another program or framework.

Developing

The developing section details internal implementation and starting points for extending components of the project. 

  • No labels