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

Quick Start Templates

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

Install and Use Quick Start

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

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

Writing Quick Start

All users

Definitions and examples of the most commonly used syntax

User Manual Template

New and experienced users of all technical backgrounds

A complete reference guide describing how to use the application

• 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)

• Glossary

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

Common User Manual Structure

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) Chapters concentrating on each benefit of the application including robust examples, and definitions and code snippets of all associated attributes, options, styles, output considerations, troubleshooting steps and solutions. FAQ (Frequently Asked Questions) Additional resources list Glossary Index

Technical Manual Template

For developers, testers, and experienced users

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

Contributor Manual Template

All users

Syntax and Code Dictionary

All users

List of all syntax and commands

README Template

1. What the project does

2. Whom it’s for

3. Operating systems and/or platforms it runs on

4. Any dependencies and requirements

5. How to install it, or a pointer to in-depth directions

6. Links to help and contact info

7. License

Write it for someone who has never heard of your project. Define terms and acronym. Link to more complete docs, tutorials, how-to materials.

• Packaged with the gem and presented on repository home page

General Information Configuration instructions Installation instructions A file manifest (list of files included) Operating instructions (or link to docs) Copyright and licensing information AUTHORS Credits THANKS Credits and acknowledgments Contact and Help information Known bugs and instructions on reporting new ones Troubleshooting Credits and acknowledgments Changelog, detailed, intended for programmers News, basic changelog, intended for users

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