Docs Information Architecture

Docs Information Architecture

This wikipage is related to issue #366.

1. Make a list of all of the parts of the Asciidoctor toolchain.

2. Make a list of the different types/stages of Asciidoctor users.

What parts of the toolchain are missing?

Just a few types of users have been added. We need to flesh out the groups and add (or cut).

Asciidoctor Toolchain

• Core

  • Syntax

  • Parser

  • AST

• Viewing Tools

  • Docgist

  • Firefox Plugin

  • Chrome Plugin

  • Guard with Live Reload

• Editing Tools

  • Brackets

  • Atom

• Converters

  • HTML5 / XHTML5

    • Custom stylesheets

  • PDF

  • EPUB

  • DocBook

  • Latex

  • Reveal.js

  • Deck.js

  • DZSlides

  • Man pages

  • fopub (archived)

• Diagrams and Equations

  • PlantUML

  • Ditaa

  • Shaape

  • BlockDiag, SeqDiag, ActDiag, NwDiag

  • GraphViz DOT

  • Salt

• Asciidoclet

• Plugins

  • Gradle

  • Maven

  • Gulp

  • Grunt

  • Leiningen

  • Ant

  • sbt

  • Intellij

  • Eclipse (in progress)

• Implementations

  • Ruby (Core)

  • Java

    • Groovy DSL

  • JavaScript

• Web Publishing

  • Confluence

  • Jekyll

  • Middleman

  • Awestruct

  • Editions

• Docker Container

  • Asciidoctor

  • AsciidoctorJ

• Extensions Lab

• Distributions

  • RubyGems

  • Debian

  • Fedora

• Organization infrastructure

  • Doctest Suite

  • html-pipeline (infrastructure for GitHub)

  • RPM package spec

  • webjars

  • Yard

  • Rdoc

  • Javadoc

Asciidoctor Users

Group 1

• Needs:

  • I want to try Asciidoctor.

  • I do not have any prior exposure / experience with Asciidoctor.

• Core Requirements:

  1. Common Syntax

  2. No installation / No prerequisites

  3. Local or Browser Editing

  4. Browser Viewing

     1. HTML Converter

Group 2

• Needs:

  • I want to try Asciidoctor.

  • I want to learn the AsciiDoc syntax.

  • I want to install and run it on my computer.

  • I do not have any prior exposure / experience with Asciidoctor.

• Core Requirements:

  1. Common Syntax

  2. Install

     1. Windows

     2. Mac OS

     3. Linux

        1. Package

  3. Local or Browser Editing

  4. Local or Browser Viewing

  5. Converter

Group 3

• Needs:

  • I want to use Asciidoctor to write my website’s content (web publishing).

• Core Requirements:

  1. Common syntax

  2. Group 1 or 2 Install and Usage

  3. Push to web publishing platform

• Need Specific Requirements:

  1. Integrate with we publishing platform

     1. Confluence

     2. Jekyll

     3. etc…​

Group 4

1. Build Docs with <build-tool-name>

Group 5

1. Convert to <name-of-alternative-converter>

2. I want to convert my AsciiDoc document to [pdf, EPUB, DocBook…​]

Group 6

1. Customize stylesheet for <name-of-alternative-converter>

Group 7

1. Use the AST

Group 8

1. Write a book with Asciidoctor (advanced syntax)

Group 9

1. Add diagrams and equations to content (advanced syntax)

2. I want to use advanced syntax/extensions (diagram, chart, emoji, equations/stem)

Group 10

1. Developers writing with Asciidoctor (advanced syntax (source code highlight, UI macros))

Group 11

1. Integrate Asciidoctor into your <continuous-integration/delivery-pipeline>

2. I want to integrate Asciidoctor in my toolchain (sbt, maven, gradle)

Group 12

1. I want to contribute to Asciidoctor

Group 13

1. I want to write extensions for Asciidoctor

Group 14

1. I want to integrate Asciidoctor in my [Java, Ruby, JavaScript, Groovy] project

Questions Asciidoctor users have.

1. I want to learn the AsciiDoc syntax

2. I want to remember the AsciiDoc syntax

3. I want to try Asciidoctor

4. I want to edit AsciiDoc like a pro

5. I want to convert my AsciiDoc document to HTML, PDF, EPUB, DocBook, etc.

6. I want to use basic extensions (font-based icons, stem)

7. I want to use advanced syntax/extensions (diagram, chart, emoji)

8. I want to integrate Asciidoctor in my toolchain (sbt, Maven, Gradle)

9. I want to write extensions for Asciidoctor

10. I want to contribute to Asciidoctor

11. I want to integrate Asciidoctor in my Java, Ruby, JavaScript or Groovy project

Concepts and Constraints

Some documentation is only useful once, for instance installation guide, when you are done you don’t need it anymore, but the common syntax is always useful.

In the current page, the section "The Basics" is too "scary". It’s better to let the user try before telling him "Why" or "Who" or "How A differ from B". Maybe it’s my way of learning new technology but the first thing I want is to start using the technology, then enjoying it, then get stuck, then read the documentation.