The focus of this meeting will be to gather requirements for a frontend tool whose purpose is to manage and build a documentation project based on software and design assets primarily from the Asciidoctor ecosystem.
Ultimately, these requirements should address these two outstanding questions:
-
"How are the various parts of the Asciidoctor project distributed?"
-
"How are the various parts of the Asciidoctor project integrated?"
We want to set out on a course to mindfully create a specialized build tool (or tools) for the Asciidoctor ecosystem that allows teams to productively and efficiently write, collaborate on and publish their documentation. In other words, we need start the process of gathering and shaping the requirements (probably on the wiki).
Down below are some open questions. We don’t need to answer them all in one day. We do, however, want to make sure we are asking the right questions.
-
Asciidoctor (core) needs to parse and render extremely FAST
-
Most lines of code in Asciidoctor are hand optimized for speed and efficiency
-
Every change to core is benchmarked before being included
-
-
Asciidoctor needs to be lightweight
-
Asciidoctor doesn’t like dependencies, can run without any additional libraries
-
The tools, however, should leverage well-established infrastructure (e.g., Bower)
-
-
Asciidoctor needs to provide functional parity with the asciidoc command
-
For this reason, Asciidoctor must have a basic CLI for single-file processing
-
Parity is an essential factor to becoming the leading AsciiDoc implementation
-
-
Haml, Slim and ERB template versions are maintained for each built-in backend as reference
-
Custom backends (e.g., deck.js) only need to be written for one template engine
-
Slim is the preferred template engine for SGML / XML output formats
-
-
Asciidoctor must cross-compile to JavaScript using Opal to generate Asciidoctor.js
-
Users (as opposed to developers) should not be required to clone git repositories to use the software
-
What are the list of assets that need to be:
-
Managed?
-
Integrated?
-
-
How should the assets in the Asciidoctor ecosystem (custom backends, themes, etc) be:
-
Structured / organized?
-
Packaged / distributed?
-
Maintained?
-
-
What backends should be supported in Asciidoctor (core) out of the box?
-
What should be the role and/or functionality of:
-
the Asciidoctor (core) CLI?
-
Hyla (or similar)?
-
-
What are the user’s expectations for a frontend documentation build tool?
-
Where do gaps exist in the tooling today?
-
What is the lifecycle of a new Asciidoctor user?
-
What is our policy on dependencies in the Asciidoctor projects?
-
Which template engines should be used for the external backends?
-
Themes (i.e., CSS stylesheets and related design assets such as fonts and images)
-
Backend templates (for use with the built-in template renderer)
-
Renderers (e.g., Asciidoctor PDF)
-
Third-party web components (e.g., deck.js)
-
Browser plugins (e.g., LiveReload, Asciidoctor.js Browser plugins)
-
Project templates and content samples
-
Asciidoctor extensions, especially syntax extensions (i.e., macros, processors, etc.)
-
Build tool integrations (e.g., Maven, Gradle, Ant, SBT, etc)
-
Incremental builders / file watchers (i.e., Guard plugin)
-
…
-
Bower for retrieving web components such as deck.js. Font Awesome, etc. ?
-
QUESTION: Will this present a problem for the AsciidoctorJ integration? Perhaps webjars?
-
-
A single interface (command) for managing a documentation project
-
Automatic download of third-party web components like deck.js and Font Awesome
-
Copy documentation assets (stylesheets, images, videos, etc) to output directory
-
Watch for changes and regenerate output
-
Apply custom themes from theme repository
-
Setup new projects from scaffolding
-
Add new files to project sources copied from prototypes
-
…
-
Foundation 5 (specifically the foundation command) - web frontend (CSS/JS) framework
-
Bower - package manager for web components
-
Sphinx - documentation build tool for reStructuredText content