Roadmap
This page is an initial draft of the Asciidoctor Roadmap. Many of the topics below are present to facilitate brainstorming and discussion. Do you have ideas about how to improve the project? Do you have ideas about what you would like to see in the project in the future?
Summary: The web and publishing continue to move forward at a rapid pace, and so must AsciiDoc.
While the focus for AsciiDoc will always be on keeping markup to a minimum, new macros are necessary to keep up with the times.
Status:
Issue #(s):
This wiki page serves as a whiteboard for ideas about new syntax.
Summary: Other than deck.js, what backends are available for Asciidoctor?
Status: In discussion
Issue #(s): 113, 242
-
What backends are available for Asciidoctor?
-
deck.js
-
HTML5
-
DocBook
-
-
Are there additional backends currently being developed?
-
Are there any stalled backends?
-
Are there any backends the community is interested in developing in the future?
-
New HTML5 backend to replace AsciiDoc default. Possible names: semhtml5, html5-sem
-
Summary: Are there any known Asciidoctor produced deck.js presentations we can show as an example on the website/documentation?
Status: In discussion
Issue #(s):
Summary:
Status:
Issue #(s):
Summary: Create a DEB package for Asciidoctor for installation on Debian and other Debian distros such as Ubuntu and Mint.
Status: Unknown
Issue #(s): 216
Alex Soto suggested using FPM to build an Asciidoctor package.
An issue report for Asciidoctor was submitted to Debian. How do we determine the status of the the request?
Summary: What stylesheets are available for Asciidoctor’s HTML output?
Status: In discussion
Issue #(s):
-
What stylesheets are available for Asciidoctor?
-
Asciidoctor
-
Foundation
-
Foundation (Potion)
-
Foundation (Lime)
-
Iconic
-
Riak
-
Golo
-
Read the Docs
-
Maker
-
Colony
-
Rubygems
The themes listed above can be previewed here.
-
-
Are there additional stylesheets currently being developed?
-
Are there any stalled stylesheets?
-
Are there any styles the community is interested in developing in the future?
|
Note
|
There is currently little documentation regarding the existence of the default and these included stylesheets. |
Summary: What tools can use and/or support AsciiDoc or Asciidoctor online and locally?+ Status: In discussion+ Issue #(s):
What tools can use and/or support AsciiDoc or Asciidoctor?
-
GitHub
-
Gist
What are support criteria or requirements?
How will we represent these?
Summary:
Status:
Issue #(s):
Summary: The content in the website sidebar is currently in the template which makes locating, editing, and excluding it messy.
Status: Planned
Issue #(s):
Summary: The bulk of the current home page content is pulled from the ReadMe and doesn’t reflect the latest news, features, or community conversations regarding the project.
Status: Brainstorming
Issue #(s):
Replace the ReadMe content with more timely information. Suggestions include:
-
Top three benefits of Asciidoctor
-
New and upgraded feature announcements and information
-
Documentation spotlights: Showcase how to use a feature/syntax and/or helpful tips and tricks
-
Usecase explorations: How people are using AsciiDoc/Asciidoctor
Summary: Documentation page is currently a list of links that is only going to get longer.
Status: Brainstorming
Issue #(s):
Depending on a user’s experience and their needs, they may be searching this page for Asciidoctor information or AsciiDoc information. A single column approach may make 50% of users scroll extensively for their topic. Mixing AsciiDoc and Asciidoctor documentation by topic could become confusing.
If the layout were shifted to 2 columns, AsciiDoc and Asciidoctor information could be placed side by side but not mixed. However, alternate layout ideas should be considered and explored.
Additionally, clean and clear ways of stating what information is in each document should be represented on the page:
-
so users can feel confident about what they are clicking on/not having their time wasted
-
so page isn’t just a list of links
-
but balancing content so that page doesn’t look cluttered/overwhelming
Summary: What other top level pages, if any, would be useful to users?
Status: Brainstorming
Issue #(s):
A page for:
-
Each big module? (What’s the criteria for a module being big/important?)
-
Roadmap?
-
FAQs?
-
Theme showcase?
Summary: A logline is a one sentence description of the project.
Think of it as the most powerful but most concise point of the project that you would say to someone as the doors of an elevator closed between you.
Will they be interested enough from that one sentence to look up the project online afterwards?
Status: In discussion
Issue #(s):
Summary: What are the benefits of using Asciidoctor? Determining and refining the main benefits of the project will help potential users quickly determine if the project will help them. Clarifying these benefits will also help users and developers explain the project to other people.
Status: In discussion
Issue #(s):
Summary: The ReadMe is out-of-date.
Status: Planning
Issue #(s):
The ReadMe content is out-of-date.
-
What is the process for maintaining the ReadMe?
-
When should it be updated?
-
Are there conventions contributors should follow when updating the ReadMe?
-
Does its structure need to be reviewed?
The README serves as an alternate home page, a second entrance to the project so to speak. It should contain the core definition of Asciidoctor, high level benefits/features, a sample AsciiDoc document, basic installation instructions, a list of available plugins (or sub-projects), contribute information, license information. The content should be information that will remain mostly stable over time. It should contain links whereever applicable to asciidoctor.org for more information.
Summary: Initially, Ascidoctor’s documentation consisted of its ReadMe and rdoc.
The content from these sources was parsed and copied into smaller, more targeted documents for the website’s documentation page.
Status: Brainstorming
Issue #(s):
During the process of converting ReadMe and rdoc content to the webpage, it became evident that:
-
Some content in the ReadMe was out-of-date
-
There were numerous usage scenarios that were not documented at all or lacked a great deal of detail
What syntax, features, installation instructions, usage, etc. documentation/how-to’s/tutorials for the Asciidoctor are missing, incomplete, or out-of-date?
Missing ReadMe information:
-
General instructions for how to use and create backends
-
Basic usage instructions for using Guard
Documentation missing from the website:
-
General backend instructions
-
deck.js
-
Maven plugin
-
Gradle plugin
-
Java integration
-
How Asciidoctor/AsciDoc differs from Markup
-
Fedora rpm package process and usage
-
Bug reporting and feature request guidelines
-
Contribution/pull request guidelines
-
Custom stylesheet creation
-
Custom and included stylesheet usage
-
Descriptions of default and included stylesheets
Summary: There are no clear instructions for how to use backends.
Status:
Issue #(s):
The backends' ReadMe needs to be updated with the following information:
-
What is a backend?
-
Why would I use a backend?
-
What types of backends are available in Asciidoctor?
-
Are there prerequisites for using a backend?
-
How do I use a backend?
-
List the available attributes.
-
Can I create a custom backend?
-
How do I create a custom backend?
Summary: How do we present the latest happenings in the Asciidoctor community?
Status:
Issue #(s):
What would be the best/most appropriate ways to present news such as new features, code updates, patches, documentation, collateral, events, outside publicity, etc.
News channels include:
-
Blog posts
-
Mailing list/Forum
-
IRC
-
GitHub
-
Twitter
-
G+ page
-
Lanyard
-
Should any of these channels be fed onto the home page of the website?
-
If so, how much of the content should be fed onto the home page?
-
-
Should any of these channels have their own webpage/top level navigation on asciidoctor.org?
-
Blog posts, which currently consist of project announcements, have their own page on asciidoctor.org.
-
The mailing list has top level navigation, labeled Discuss.
-
The repository has top level navigation, labeled Code.
-
Summary: Richfaces example
Status:
Issue #(s):
Summary: How will we represent events (live webinars and podcasts, conference talks, etc..) where Asciidoctor is being talked about or demonstrated?
Status:
Issue #(s):
Summary:
Status:
Issue #(s):
Summary:
Status:
Issue #(s):
Summary:
Status:
Issue #(s):
Summary:
Status:
Issue #(s):