When the Solr Ref Guide was donated back in 2013, we decided to host it in Confluence (cwiki) because the source had originated from a Confluence system, and it made the handoff easier. Today, though, it has become really painful to maintain there.[1]
I'll suggest that it's time to move from Confluence to something else. As a replacement, I propose to migrate all of the existing content to text files in Asciidoc format. This is a lightweight markup language similar to Markdown, but intended for use by writers. We can then use a static site generator (I've chosen Jekyll) to produce templated HTML pages, and Asciidoctor tools to make PDFs (and ePub if we want). At this point, we'd be able to treat the docs the same way we do code - source controlled and open for patches by anyone. We can integrate the doc publication process with the release process (as much or as little as we choose). With the Apache Comment System, we would retain the ability for users to comment on pages. Since we'd control the hosting, we can choose which versions we retain online for users. The source for each version would be maintained in the appropriate branch, allowing us to go back at any time and edit older versions when necessary (or build a new version from an older branch). I've worked up a proof of concept for these ideas, and have most of the building blocks for this solution in place in a GitHub repo at https://github.com/ctargett/refguide-asciidoc-poc. I've used that to put up a demo of the various ideas I worked through, to show what it might look like online and in PDF, at http://home.apache.org/~ctargett/RefGuidePOC/. I'm trying to keep this introductory mail brief but if you want more info, I've fleshed out a lot of details of the approach (and how I made a few key decisions) in the README and other pages in the GitHub repo linked above. There are still a number of issues to work out - where the pages will actually live, where they'll be hosted, how we'll implement search (heh), finishing the styling, finalizing the build scripts, etc. But I hope the project shows enough promise that we'll agree to move forward with this approach. If reaction is positive, my next step will be to expand the demo online with a full copy of the Ref Guide instead of the current small set. I look forward to hearing your thoughts or questions about this proposal. Cassandra [1] For those who have avoided the pleasure of working with Confluence, there are many reasons to move off Confluence, but here are a few: * Confluence as a product is no longer designed for our use case and our type of content. While technical documentation was once a core competency, the product is now much more focused on team collaboration. This shift has left us out a bit. * The writing/editing experience is painful and a barrier for all users, who need to learn a lot of Confluence-specific syntax just to help out with some content. Non-committers can't really help much except to point out problems and hope someone else fixes them. Committer involvement is low, and perhaps could be improved with a solution that's easier to use. * We really can't maintain online documentation for different versions. Users on versions other than the one that hasn't been released yet are only given a PDF to work with. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
