We’ve been discussing on another channels improvements for
arquillian.org website. I would like to summarize them here and move the discussion forward.
There are several aspects, where one of them is certainly toolchain and build, but I would like to focus on the content in this thread. For all the things build there is another thread where I’m also eagerly looking to your feedback.
Currently we do not provide unified access to our documentation. Some of the projects are hosted in Confluence, others have their own github pages and some just plain README or GH Wiki. And I’m only talking about those which are part of Arquillian organization. From my point of view the best strategy would be to go with Asciidoctor and
gh-pages for two main reasons:
- It’s the most community/contribution friendly solution - just click edit and hack away
- it’s out-of-the-box accessible - see http://arquillian.org/arquillian-cube
Another option would be to use gitbook, like WildFly Swarm team does - https://wildfly-swarm.gitbooks.io
Last thing would be to create new section and expose those docs on the front-page but that’s rather easy.
There is another thread where I started capturing ideas around release announcements automation. One thing I would like to bring up here is the automated summary of what the extension is about. Currently it’s very generic and sometimes confusing. If there is no authored release notes the only thing we present to the user is “What is Arquillian”, release notes based on issues and pom details. Instead of “What is Arquillian” which the reader should already know anyway, we should provide details about the extension itself. This could be simple file based on some naming convention sitting in the root of the repo which we can extract while generating the post. Thoughts?
Then, there is one page which not exposed by any link but has a lot of interesting content http://arquillian.org/code/
I think we should merge it with the overall documentation somehow