Documentation Architecture

This document has two purposes:

1. To describe the Asciidoctor project’s documentation requirements and objectives

2. To map the workflow tasks and automation routes needed create and maintain the documentation.

Audiences

The Asciidoctor project serves a wide variety of end users.

To assist new and experienced users, at a minimum, the project needs to maintain:

• Install and use quick start (Core)

• Writing quick start (Docs)

• User manual (All)

• Technical manual (All)

• Contributor manual (Docs and Core)

• Syntax and Code Dictionary (All)

• README (All)

What is the Docs Repo?

The Docs Repo will be where all of the compiled documentation relating to the Asciidoctor organization will be stored. It will also be where documentation that is not packaged with individual repositories will be stored.

How does it operate?

The Docs repo will consist of files that will be linked to the docs and source code in individual repos. These files will update automatically when changes are made to linked docs and/or code in individual repositories. Publication sources will then pull from the Docs repository for content (ex. the documentation displayed on the project’s main website.

What does each repository need to provide?

1. /docs folder

2. README

3. Reference Doc that contains definitions and working usage examples of all attributes, options, styles, configurations

4. Quickstart which contains requirements, installation, configuration and basic usage instructions with examples

5. API reference documentation

6. Changelogs

7. branch solely for updating the documentation

8. Code examples are to be pulled directly from the source code or test suite

Overview

• Each project repository in the Asciidoctor organization will have its own documentation, which will be stored in a top level file named docs.

• Screenshots, images, figures, etc. for the documentation will be stored in docs\assets\.

• Code snippets and examples should be linked and automatically extracted from the source code or test cases to ensure accuracy.

• The code must be tested.

• The Asciidoctor organization Docs repository will build each projects' documentation for publication on the Asciidoctor project.

• It will also build additional and alternate forms of documentation from content and code flagged and included throughout the repositories.

Quick Start Templates

Contains requirements, installation, configuration and basic usage instructions with examples

Install and Use Quick Start

Basic instructions showing how to install, run, and produce default output

Audience

For users with technical experience and knowledge of previous Asciidoctor versions and the AsciiDoc syntax

Writing Quick Start

Definitions and examples of the most commonly used syntax

Audience

All users

Technical Manual

A complete reference manual defining the source code and how it operates.

Audience

Developers, testers, and experienced users

Writing style

Concise but conversational

Technical Manual Template

Pending

Contributor Manual Template

Audience

All levels of users and developers

Writing style

Conversational

Contributor Manual Template

Pending

Syntax and Code Dictionary

List of all syntax and commands

Audience

Users and developers

Writing style

Extremely concise

Documentation Webpage Topic flow (aka the navigation)

Getting started

• Introductions

  • Hello! If you’re here…​

  • What is Asciidoctor?

• Key features

  • Compare to MarkDown

  • Compare to AsciiDoc

• Quick-start and output guide

• Installation

• Requirements

  • Terminal

• Install the Gem

  • Extensions and Options

• Commandline Usage

  • Basic Commands

  • from --help

• API Usage

  • Basic Commands

• Output formats

• Text Editor

Write your Content

• Document anatomy

• Header, Title and Author

• Text and Paragraphs

  • Preventing Substitutions

• Sections

• Lists

• Tables

• Blocks

• Admonitions

• Links and Cross references

• Images and Videos

• Document Attributes

• Sourcecode highlighting

• Callouts and Icons

• Footnotes

• TOC

• Metadata

Stylesheets and Outputs

• Default stylesheet and backend

• Stylesheet factory

• Custom stylesheets

• DocBook

• Slideshows

  • Deck.js

• Custom backends

• Previewing a document

Publishing

• Locally

• Multipart books and large documents

• GitHub

• Awestruct

• Blogdiggitty

Enriching the output

• Attributes and Chunks

• Chunking content and metadata

• Includes

• Font Icons

• Images dir

• Section links

Converting to Asciidoctor

Markdown

Build Integrations and Implementations

• Java

• Gradle

• Maven

• JavaDoc

• Javascript

• Yard

• Rdoc

Community

• Getting Help

• Contributing

  • Content

  • Code

• Issues and Requests

• Roadmap

• History

Resources

• A Short Manual of Nearly Everything Asciidoctor

• API Doc

• Presentations, Screencasts and Videos

• Asciidoctor in Use