+1 with Asciidoc and moving off Confluence and into anything that allows to generate stable-version HTML export. Offline builds that can also be used for tooling (e.g. for search index generation) is also great. I had a quick look at indexing Confluence export and it is a confusing mess (though I am sure possible).
Regards, Alex. ---- Newsletter and resources for Solr beginners and intermediates: http://www.solr-start.com/ On 19 August 2016 at 07:54, Jan Høydahl <[email protected]> wrote: > I was thinking about Asciidoc as well the other day, I love it! > > +1 > > -- > Jan Høydahl, search solution architect > Cominvent AS - www.cominvent.com > > 18. aug. 2016 kl. 21.45 skrev Cassandra Targett <[email protected]>: > > 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] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
