Home

Documentation Brainstorming

User Manual Chapters and/or Guides for Asciidoctor (recommended by @lordofthejars in Issue #88:

• How to install / render a document

• Reference

• Customizing (templates, stylesheets, ..)

• Working with Ruby (which includes how to write filters, extensions, extensions, …​)

• Toolchain (Java, Maven, Gradle, Asciidoctor.js, …​)

From Issue #3 on asciidoctor.org:

As the goal of the new users guide is to be brief and to get them writing in AsciiDoc ASAP, I think most of the content prior to the Writing in AsciiDoc: First Steps section is just way too much backstory.

What do people think of removing most of that content and instead use it to create "What is AsciiDoc", "Why Use AsciiDoc", "How AsciiDoc Renders your Opus" guides? -@graphitefriction

I think that’s the right way to go. Once we setup the website build, it will be much easier to tie the various documents together, perhaps so they flow very naturally from one to the next. We could even think of them as chapters of a book.

The backstory is important in this case (even though I’m often critical of backstory) because the first question I always get asked is "What is AsciiDoc?" and "Why should I use AsciiDoc (instead of Markdown)?" It will be good to get these responses out there. -@mojavelinux