Asciidoctor Community Meeting

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Asciidoctor Community Meeting

graphitefriction
Administrator
Dear Asciidoctor Community,

It's time to review the Asciidoctor Project's infrastructure and integrations and discuss new ideas, changes, and solutions to current problems in order to keep the project lean, mean, and focused like a hungry hawk.

To jump start this discussion, we're going to have a meeting in the #asciidoctor IRC channel.
(If you want to see the discussion that spawned the need for a meeting, checkout this snippet from the #asciidoctor IRC log.)

Don't worry, this meeting will have a ruthlessly-honed, hardcore agenda that will be posted prior to the meeting time. I know your time is extremely valuable, and meetings are typically the last place we want to be.

First, we need to choose a time when the majority of the community who would like to help with the project's infrastructure and integrations, can meet.

I've set up a scheduling poll on Doodle where you can check off the times you're available. Since the majority of the community is in Europe, I set the poll up in the Brussels time zone. The poll will close at 11:59 MST on Monday, and then I'll announce the meeting time here.

In the next 24 hours, I'll also post the meeting agenda. Please, don't hesitate to post ideas, concerns, questions, etc. to this thread. If possible and appropriate, I'll wrestle them into the agenda.

Cheers,

Sarah
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor Community Meeting

graphitefriction
Administrator
Hello Asciidoctor Community!

The meeting will be held on January 16, 2014.
Start time: 7:15 PM CET (18:15 UTC)
End time: 8:30 PM CET
This time range allows the most people to attend at least part of the meeting.

Location: #asciidoctor IRC channel

Agenda: I'll post it as soon as Dan and I are done arm wrestling over the fate of item #7 (score: Sarah: 2, Dan: 1.5, Pint glass: 1, Sneeze: 1).

Cheers,

Sarah
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor Community Meeting

mojavelinux
Administrator
Hey everyone!

I've prepared notes and an agenda (the open questions) for the meeting. I've saved it as a gist and copied the content into this message. We aren't looking to solve every problem. The main focus of the meeting, as I say in the notes, is to make sure we are asking the right questions and to get on the same page about where we are headed.

Feel free to suggestion revisions or other items. This won't be the only meeting we'll ever have, so if we don't get to everything, don't panic :)



Notes and Agenda

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:

  1. "How are the various parts of the Asciidoctor project distributed?"

  2. "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.

Preconditions

  • 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

Open Questions

  1. What are the list of assets that need to be:

    1. Managed?

    2. Integrated?

  2. How should the assets in the Asciidoctor ecosystem (custom backends, themes, etc) be:

    1. Structured / organized?

    2. Packaged / distributed?

    3. Maintained?

  3. What backends should be supported in Asciidoctor (core) out of the box?

  4. What should be the role and/or functionality of:

    1. the Asciidoctor (core) CLI?

    2. Hyla (or similar)?

  5. What are the user’s expectations for a frontend documentation build tool?

  6. Where do gaps exist in the tooling today?

  7. What is the lifecycle of a new Asciidoctor user?

  8. What is our policy on dependencies in the Asciidoctor projects?

  9. Which template engines should be used for the external backends?

List of Assets

  • 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

User needs

  • 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

References

  • Foundation 5 (specifically the foundation command)

  • Bower

  • Sphinx

Talk to you soon!

-Dan