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

User Manual Template

A complete reference guide describing how to use the application.

Contains definitions and working usage examples of all attributes, options, styles, configurations

• Describes each feature of the application, its benefit(s), and how to use it

• Screenshots and complete code examples are the best way to show the user what to expect and how to do it

• Troubleshooting tips

• Excellent, intuitive navigation (table of contents, index, clear next steps)

Audience

New and experienced users of all technical backgrounds

Writing style

Conversational and detailed

User Manual Template

= Title page

== Copyright and license page

== How to navigate the manual

== Table of Contents

== Description of the primary benefits and supporting features of the application.

== Quick start chapter(s)

== Individual Chapters

Each chapter concentrates on a benefit of the application.

A chapter includes:
* robust, working examples
* definitions
* associated attributes, options, styles
* output and backend variation considerations
* troubleshooting steps and solutions

== FAQ (Frequently Asked Questions)

== Additional resources list

== Glossary

== Index

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

README

The README is the minimum amount of documentation that is packaged with the gem. It is also part of the project’s landing page on GitHub.

Audience

All levels of users and developers

Writing style

The README should be concisely written. However, it should also be compelling and informative, as it will be the first document describing what your project does that many potential users will see. Make sure to define any terms and acronyms.

README Template

== Overview

* Brief description of the project's purpose and main benefit(s)
* The types of users this project helps
* Link(s) to other primary help documents and sources

== Operating systems and/or platforms it runs on

Be brief, provide links to more detailed documentation

== Dependency and configuration requirements

Be brief, provide links to more detailed documentation

== List of files/directory structure

Optional depending on the complexity of the project

== Basic installation instructions

Be brief, provide links to more detailed documentation

== Basic usage instructions

Be brief, provide links to more detailed documentation

== Copyright and licensing information

== Author(s)

== Thanks, acknowledgements, and credits

== Basic contact and help information

Provide links

== Bugs

* List of known bugs
* Instructions on reporting new bugs

== Changelog

== Basic contributing instructions

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

Tutorials

• Usually targetted at new users

• Step by step instructions demonstrating how to complete a process, use a feature, etc.

  • Purpose of the process or feature

  • Demonstration (usually with examples and screenshots) divided into brief sections

  • Review/Reiteration of tutorial purpose

  • Next tutorial and/or additional resources