Ocean-Atlas Content Standards

Ocean-Atlas Content Standards

1. Purpose

This document defines the common standards for writing and organizing content in Ocean-Atlas.

The objective is to ensure that Ocean knowledge is:

clear and precise;
consistent;
maintainable;
easy to navigate;
searchable and reusable;
suitable for both human and machine consumption.

Knowledge-type-specific structures are defined by their respective templates.

2. General Principles

Ocean-Atlas content should follow these principles:

One primary purpose per knowledge item.
Prefer clarity and precision over unnecessary detail.
Avoid duplicating canonical knowledge.
Link to existing knowledge instead of repeating it.
Separate normative specifications from explanations and examples.
Use consistent Ocean terminology.
Keep content technology-independent where the subject itself is technology-independent.
Write content so that it remains understandable outside its immediate repository context.

3. Document Structure

Every independently addressable knowledge item should follow this basic structure:

Title
Metadata
Table of Contents, when useful
Main Content
Related Knowledge, when useful

Each document must contain exactly one top-level # heading representing its title.

Example:

# Ocean Package

## Metadata

...

## 1. Overview

...

Large documents should include a Table of Contents when it materially improves navigation.

The exact content sections depend on the knowledge type and its template.

4. File Naming

Markdown files must use:

lowercase characters;
kebab-case;
meaningful and concise names;
the .md extension.

Preferred:

knowledge-architecture.md
create-rest-api.md
primary-shared-resource.md

Avoid:

KnowledgeArchitecture.md
create_rest_api.md
document-final-v2.md

index.md should be used for logical area landing pages where appropriate.

A filename is not a knowledge identity. Renaming or moving a file must not change its stable knowledge ID.

5. Headings

Headings must:

follow a logical hierarchy;
avoid skipping levels;
be concise and descriptive;
remain reasonably stable to support navigation and references.

Example:

# DSL API Reference

## 1. Overview

## 2. Syntax

### 2.1 REST

### 2.2 SOAP

## 3. Examples

Heading numbering may be used for substantial reference or architecture documents but is not mandatory for every knowledge type.

6. Writing Style

Content should use clear, direct, professional technical English.

Prefer:

short and focused paragraphs;
explicit terminology;
active voice where practical;
concrete examples where they improve understanding.

Avoid:

unnecessary repetition;
vague statements;
unexplained abbreviations;
inconsistent terminology;
conversational filler;
unnecessary implementation detail.

Terms specific to Ocean should use their canonical names consistently.

New terminology should be defined when first introduced and added to the glossary when broadly relevant.

7. Normative Language

Normative documents should use requirement terms consistently:

must — mandatory requirement;
must not — prohibited behavior;
should — recommended unless there is a justified reason otherwise;
should not — generally discouraged;
may — optional or permitted.

These terms should only be used normatively when the document has sufficient authority to define requirements.

Guides, tutorials, and examples should avoid presenting recommendations as mandatory platform rules unless they reference an authoritative specification.

8. Code and Ocean DSL Examples

Code and DSL examples must use fenced code blocks with an appropriate language identifier where available.

Example:

func main() {
    // ...
}

Ocean DSL examples should use the configured Ocean syntax identifier when supported by the rendering environment.

Examples should be:

minimal enough to understand;
valid whenever presented as executable or compilable;
focused on the concept being demonstrated.

Partial or conceptual examples must be clearly identified as such.

Examples must not silently introduce behavior that contradicts canonical specifications.

9. Cross-References and Links

Knowledge relationships should use stable knowledge IDs according to the Identity and Relationship Standards.

Example:

dsl.package

References should prefer canonical knowledge when explaining authoritative behavior.

Ordinary Markdown links may be used for:

external resources;
navigation;
rendered website links.

Semantic relationships between Atlas knowledge items must not depend solely on fragile file paths or URLs.

Avoid duplicating substantial content merely to avoid creating a cross-reference.

10. Images and Diagrams

Images and diagrams should only be used when they improve understanding.

Where practical:

prefer maintainable text-based diagrams such as Mermaid;
store shared static resources under assets/;
use meaningful filenames;
provide descriptive alternative text;
keep diagrams consistent with the surrounding documentation.

Essential knowledge must not exist only inside an image.

Diagrams should complement textual knowledge rather than replace necessary explanations.

11. Tables and Lists

Use tables when comparing structured information with consistent attributes.

Use lists when presenting:

requirements;
options;
steps;
related concepts.

Avoid large or deeply nested tables when simpler sections or lists would be easier to maintain and read.

Formatting should improve comprehension rather than decorate the document.

12. Content Granularity

A knowledge item should represent one coherent primary subject.

Split content when:

multiple independently useful concepts are combined;
sections require separate lifecycle or version management;
sections need independent stable identities;
the document becomes difficult to navigate or maintain.

Do not split content merely to create small pages.

The goal is semantic coherence, not a specific document length.

13. Canonical Knowledge and Examples

Canonical specifications define behavior.

Examples demonstrate behavior.

Guides explain how to accomplish tasks.

Tutorials teach through a sequence of steps.

These roles must remain distinct.

When an example or guide describes behavior defined elsewhere, it should reference the canonical knowledge rather than redefine it.

If a conflict exists, current authoritative canonical knowledge takes precedence.

14. Version-Specific Content

Version-dependent behavior must be clearly identified.

A document should not ambiguously mix behavior from incompatible Ocean versions.

Where knowledge applies only to particular versions, the applicable version or range should be represented through metadata and, when necessary, explained in the content.

Historical information should remain distinguishable from current guidance.

15. Generated, Imported, and Derived Content

Content that is generated, imported, or derived must be identifiable through metadata.

Generated content should not be manually edited when it has an authoritative generation source unless explicitly permitted by its maintenance process.

Imported or derived content should preserve sufficient provenance to identify its origin.

Canonical manually maintained knowledge must remain distinguishable from generated summaries or derived representations.

16. Quality Requirements

Before knowledge is accepted or approved, it should be checked for:

correctness;
clarity;
completeness appropriate to its purpose;
consistent terminology;
valid metadata;
valid stable identity;
valid internal references;
appropriate relationships;
version applicability where relevant;
consistency with authoritative Ocean knowledge.

Content should not be accepted when it knowingly contradicts current authoritative knowledge without explicitly documenting the conflict or intended change.

17. Technology Independence

These content standards define the logical representation and quality of Ocean knowledge.

They must not depend unnecessarily on:

a particular documentation website;
repository hosting platform;
Markdown renderer;
search engine;
database;
AI provider;
RAG implementation.

Markdown is the initial authoring format, but the meaning and organization of knowledge must remain portable to future presentation and storage technologies.