At the risk of sounding presumptuous, I think this is the wrong question to ask. Here are my thoughts.
> Not everyone knows AsciiDoc
I recognize that there will be a transition period as people become accustomed to AsciiDoc, as with any new technology. AsciiDoc is catching on quickly, though, so I expect this issue to subside proportionally.
Often times, I'm able to get over that hump by saying, "it's similar in spirit to Markdown". That helps them understand what type of tool they should use to read it (i.e., a text editor). Keep in mind we continue to improve the live preview tools like the add-on for Atom (see https://atom.io/packages/asciidoc-preview)
> AsciiDoc can be hard to "read" in its non output form when reviewing
The whole idea of AsciiDoc is that it is easy to read in raw form. Admittedly, there are times when it is not. I think we need to work from both ends to solve the problem. One one end, we need to write simpler documents. Cutting out excessive formatting is better for everyone (including the reader). On the other end, we continue to work to make the syntax simpler (either by modifying core or adding extensions). AsciiDoc isn't perfect, and experience will tell us where and how we can simplify it.
> I don't really want people adding comments to AsciiDoc file itself even if they could read AsciiDoc as they probably will mess up syntax somewhere.
Again, I'd argue this is actually the point of AsciiDoc. People add inline or block comments to communicate back and forth. As they are addressed, those comments can be removed. This is how I collaborate on AsciiDoc and I've found it to be very effective. If the reviewer understands a few rules, they can avoid breaking the document rather easily in my experience.
> Ideally, there would be some nice PDF viewer that we could share a document and everyone would see everyone's feedback as its added to a document.
This goes against our philosophy in Asciidoctor. Our philosophy is that docs should be treated like code. They should be committed to a revision control system and that revision control system should be used to manage the collaboration (edits, additions, deletions and comments). When you go to PDF, you put up a huge barrier to collaboration and ownership.
> if I send them an AsciiDoc to review won't really know what to do with it....
They are smart people. I'm confident they'll figure it out :) Most of the time, people are just resisting change. We need to nudge them ;) The benefits of AsciiDoc far outweigh the inconvenience and a little training.
Keep showing folks the right way to work with the technology. Keep supporting and enabling them everyday.
Atom and ALP is the fast-track to acceptance for many I've introduced AsciiDoc to. And once RedPen AsciiDoc validation support is added into the Atom package, that will be another barrier removed.
You'll also discover the technology behind DZSlides, which Hubert uses for the visuals in his talk.
In this post, I explain how we plan to use BountySource's new funding platform, Salt, to sustain the pace of innovation in Asciidoctor and build the hacker-friendly publishing toolchain authors like you have always wanted!
I've had a wild ride in my journey in open source thanks to and the wider community like and
Now is the time for us as a Tech Comms community to put our money where our mouths are and rustle up some serious funding for this organization. Even if you can't donate personally, I'm sure that you could use your skills of persuasion to convince your organization to commit to supporting such a vital Tech Comms standard.
I'm going to do whatever I can to get things moving in the right direction. Up towards the funding goal.
What will you do?
Thanks and !
Open and forkable, just like it should be. Don't know whether I should pick a license for it or not. If you think I should, suggest a good one in the comments.
It was a great night giving some background on AsciiDoc, and demonstrating some great examples of Asciidoctor projects. Technology like AsciiDoc and Asciidoctor promotes action. Some folks have gone off and created their own fork of 's http://hubpress.io project to get blogging and practicing AsciiDoc.
- OpenDevise, Inc.Vice President, 2013 - present
- Red Hat, Inc.Principal Software Engineer, Author, Open Source Advocate, 2013
- Benefit Software Inc.
- TeleCommunication Systems
- SI International
- CodeRyte, Inc.
During a short stint at the University of California, Santa Barbara, following his graduation from Cornell University, Dan became captivated by the world of free and Open Source software (FOSS). It was his involvement in FOSS while living in California that helped him transition into the software development industry. He gradually discovered the combination of Linux and the Java EE platform to be the ideal blend on which to build his professional career. In his search for a robust Web framework, Dan discovered Seam, which was quickly granted this most coveted spot in his development toolbox. The rest, as they say, is history.
Dan lives with his wife and pet chinchilla in Laurel, MD, where he can often be found shouting at the TV during sporting events or working out his golf swing at the driving range. When not at home, he's likely traveling to worldwide software conferences and savoring Belgian beer and chocolate.
- Cornell UniversityMaterials Science & Engineering, 1996 - 2000
- University of California, Santa BarbaraMaterials Science, 2000 - 2001
- Col. Zadok Magruder High School
AsciidocFX: An Editor for Asciidoc Markup Language | Javalobby
AsciidocFX is editor for Asciidoc Markup Language. It is a basic editor that reflects any changes in editor to Preview Pane immediately. Doc
Asciidoctor.js 1.5.0 released to Bower and npm! | Asciidoctor
The release train is on the move! Version 1.5.0 of Asciidoctor.js has been released and is now available in Bower and npm. This release is a
Asciidoctor Gradle plugin 1.5.0 released! | Asciidoctor
It took us longer than what we hoped but Asciidoctor Gradle plugin version 1.5.0 is finally here! The Asciidoctor Gradle plugin is based on
Asciidoctor Maven plugin 1.5.0 released! | Asciidoctor
The West may still be suffering from a dry spell, but we're excited to shower Maven users who have been experiencing one with the release of
Plain-text diagrams take shape in Asciidoctor! | Asciidoctor
One task that still pulls your focus away, and is more difficult than it should be, is integrating technical diagrams into your documents. I
Jakub Narloch brings Arquillian to Netflix, recognized at AWS re:Invent ...
We appreciate all that Jakub has done for the Arquillian project and code quality. Jakub entered into the Arquillian community as a Google S
Arquillian Droidium 1.0.0.Alpha1 Released · Arquillian Blog
The Arquillian team is proud to announce the 1.0.0.Alpha1 release of the Arquillian Droidium component!
Introducing Asciidoctor.js live preview in your browser | Asciidoctor
I'd like to introduce you to the easiest way to render any AsciiDoc file, local or remote, as HTML directly in your browser! All you need to
Easier Documentation, Simpler Websites And Faster Collaboration @ OSCON ...
Do you find producing and collaborating on documentation or web content difficult? At OSCON 2013, we'll work with you to reduce the friction