arquillian.org: The Bridge of the Arquillian Project
The short version
Arquillian now has guides! If you want to know how to get started with Arquillian, head over to arquillian.org to check them out…in one of 8 languages! If you want to make them better, fork the website project and get involved.
The slightly longer version
When I thought of how to present arquillian.org, naturally images of alien spacecraft came to mind. These days, there’s a lot of activity flowing in an out of the Arquillian mothership. To manage and make sense of all that information, we were in need of a central view of everything. In other words, we needed to get to “the bridge” of the ship. From there we can monitor activity, publish the lastest information, collect and exchange ideas and decide which actions to take.
Well, we’ve made it, finally. Welcome to arquillian.org. As Bob McWhirter likes to say, “You’re soaking in it.”
The full story
We’ve been thrilled to witness the impact Arquillian has made over these last two years and the agility it’s brought to the Java ecosystem. There’s no question, the Arquillian invasion is in full force.
But even as we stood on stage at JavaOne to receive a Duke’s Choice Award for Arquillian on behalf of our awesome community, I kept thinking about how much more successful it could be. I mean, if developers have been able to figure out how to use and build on Arquillian so far, just imagine how many more developers would use it—and how much easier it would be for them—if the project actually had some decent guides to get started.
We felt your pain. We heard your voice.
That’s why we decided at JavaOne it was time to get serious about closing this gap by writing several step-by-step guides. We didn’t leave off there, though. We recognized the whole experience of discovering Arquillian for the first time (or coming back to it after a break) needs to be extremely easy and rewarding. So after we drafted the guides, we molded them into a visually appealing website with a call to action button you can’t possibly miss. We then called on our noble community members to volunteer to translate those guides into as many languages as possible. And they came through!
The long road
Ever since then, we have been trying to get these guides into your hands. It’s been a long and rather ridiculous journey. I describe it as ridiculous for contrasting reasons.
On one hand, the reason we couldn’t make it available was ridiculous. But that’s a long and boring story. On a positive note, it was ridiculous to see how much effort the community has contributed to driving this vision to make Arquillian easy to adopt and use—to a website that wasn’t even being published, no less. It certainly demonstrated a lot of spirit. That’s why we kept pressing against that first ridiculous reason to get it launched :)
The final stretch
Over the past several weeks, I’ve been working with Sarah and Aslak (with blood, sweat and tears) to get this website ready to publish. We have curated as much information as we can find—at least so far—and organized it into a website that’s going to give you a view into the Arquillian project like you’ve never seen before. Heck, even while building the website, I was stunned to finally see a list of modules, releases and changelogs in one place for the first time. And now, it’s finally out there.
A new beginning
This is just the beginning. By no means do I consider the website to be set in stone for you just to look at (though I need a few days off to sleep). Quite the opposite. arquillian.org is an open book. It’s a Creative Commons (CC BY-SA 3.0) open source project hosted on, you guessed it, github. Clone (or fork) the repository named arquillian.github.com and checkout the README. The project comes complete with an issue tracker and wiki.
It’s important to recognize that the website needs to be a part of the Arquillian project just like any other module. After all, the project is only as good as the information we put out there. I’m envisioning have contributors that join the website team much the same as they might join a module. The group will be a cross section of design, outreach, messaging, documentation and, of course, automation.
We got it spun up (nearly writing it twice) because we knew Arquillian was severely lacking in good documentation and reference material, but we want you to be as involved in it as you like.
The website reflects the quality of the software—especially in the eyes of new users—and therefore it represents all of our work. That’s why my favorite page on the site is the list of contributors ;) It’s all about you, the nobles.
What’s inside
Before I close, I want to mention some key highlights of the website. Then, I’ll leave you to explore and discover the rest :)
- All content managed in git and hosted on Github
- Baked with Awestruct, a static site generator
- A data curating pipeline written in Ruby (JRuby) as Awestruct extensions
- Pages written in Haml (with a mix of Textile)
- Easy to read, step-by-step guides (written in Textile, changelog retrieved via git)
- Blogs written in Textile (or Markdown)
- Guest blogs and improvements integrated via pull requests
- Layout and components built on Twitter Bootstrap and jQuery
- CSS3 goodness and cross-browser support compiled by SASS
- Designed to be responsive for mobile phones and tablets (give it a try!)
- Module, release and commit information mined from git repositories
- Auto-generated, in-depth blog entry plus custom notes for each release (example)
- Detailed summary page for each module (repository, versions, dependencies, contributors, etc)
- Contributor information backed by Github and Gravatar
- Dynamic information retrieved via json-p (tunneled through jgfeed when necessary)
- Upcoming talks on Arquillian syndicated from Lanyrd
- Blogs and articles about Arquillian syndicated from Diigo
- Under the watchful eye of Ike (as you can see in the upper-left hand corner)
If you are curious about more details, check out the Information Architecture page I drafted on the wiki about the site. Take a look at the README if you want to build the site locally.
The vision
Our vision is to automate as much as the documentation as we can possibly accomplish. It ain’t (just) because we’re lazy. It’s because we know it’s the only way to get you the most accurate, up to date information about Arquillian and to reasonably manage the growing Arquillian ecosystem. In other words, we need to be in “the bridge”. And now we have it. Just check out the module pages. What a start!
Use it. Enjoy it. Pass it on. And fork it if you want it to be better.
If words could do
I want to give a huge thanks to Sarah White, who has stuck with me through trying times to get this website looking visually stunning, organized and logical (and for just putting up with my intense focus on this project).
I also want to recognize the following translators, who have brought the guides to 8 languages in total: Markus Eisele (German), Antoine Sabot-Durand and Badr El Houari (French), Takayuki Konishi (Japanese), Hantsy Bai (Simplified Chinese), Bartosz Majsak (Polish), Jose Rodolfo Freitas (Portuguese) and Tommy Tynja (Swedish). Arquillian is forever changed because of your effort.
Finally, I want to thank all of the contributors who have embraced writing release blog entries—Vineet Reynolds, Bartosz Majsak, Karel Piwko and Lukas Fryc—and contributing guides—Karel Piwko, Paul Bakker, Lincoln Baxter and Marek Schmidt.
That’s exactly the participation I envision will make this website a key communication hub of the Arquillian project. Let’s keep the invasion strong!