Asciidoctor Documentation

Caution

The information and processes in this README are being brainstormed and discussed. They have not been implemented!

But speaking of brainstorming, we’re looking for people to add some thunder and lightning!

Do you have ideas about how to:

• automate documentation so code and references stay up-to-date?

• flag and tag documents according to versions?

• link source code to documents across repositories?

• outline and structure user-friendly manuals?

• write, edit, automate, deploy, etc. documentation?

If so, don’t hesitate to file an issue, start a wikipage, fork this repo, or join the discussion link pending on the mailing list.

Overview

The Asciidoctor Documentation project’s goal is to build, store, and distribute the content relevant to the Asciidoctor organization and its projects.

This repository will store and maintain the:

• General documentation guidelines

• General document building instructions

• Asciidoctor Organization documents (such as the Infrastructure Goals and Planning document)

• Content guides and templates for writing READMEs, changelogs, manuals, tutorials, etc.

• Source code for building documents that include content from multiple repositories

• Writer’s guide

• General contributor manual

• General developer guidelines

• FAQ

• Tutorials (which will be released to the website)

• Additional learning materials (presentations, etc.) that are cross-repository

• Project collateral

Additionally, the Asciidoctor Documentation repository will distribute each project’s documentation for publication on the Asciidoctor website. It will build additional and alternate forms of documentation from content and code flagged and included throughout the repositories.

Asciidoctor Documentation repository structure

The asciidoctor-documentation directory contains:

• README

• Infrastructure Goals and Planning

• /templates directory

  • README guide and template

  • Release Notes guide and template

  • Tutorial guide and template

  • User Manual guide and template

README	Purpose and description of the Asciidoctor Documentation project
Infrastructure Goals and Planning	Planning document outlining information, suggestions, and questions about building the Asciidoctor organization’s infrastructure.
Templates directory	Location of the content guides and templates for writing READMEs, changelogs, manuals, tutorials, etc.
README guide and template	Style and structure suggestions for a project’s README.
Release notes guide and template	Style and structure suggestions for a project’s release notes.
Tutorial guide and template	Style and structure suggestions for a project’s tutorials.
User manual guide and template	Style and structure suggestions for a project’s user manual.

Note	Many more guides and templates are planned, checkout the ideas and requests filed in the issue tracker for more information.

Documentation for Asciidoctor core and other Asciidoctor organization projects

Each project within the Asciidoctor organization and Asciidoctor core will store and maintain its own:

• Installation and usage quick start

• User manual

• Technical manual

• Syntax and code dictionary

• README

• Changelog

• License

• Specific contribution instructions

The core repository will also store and maintain the:

• Syntax writing quick start

Contributing instructions

Pending

Issues

Use this repository’s issue tracker to file issues and feature requests regarding the goals of this repository and its documents.

Build instructions

See Infrastructure Goals and Planning for more information.

General Asciidoctor Contact and help information

Project home page

http://asciidoctor.org

Core source code repository

https://github.com/asciidoctor/asciidoctor

Core issue tracker

https://github.com/asciidoctor/asciidoctor/issues

Mailing list / forum

http://discuss.asciidoctor.org

GitHub organization

https://github.com/asciidoctor