I'm a tech writer in the process of finding open source documentation tools to replace our use of MadCap Flare's single source tech writing software. We (Splice Machine) recently went Open Source, and need to transform our documentation into an Open Source system that developers can update and modify.
I've looked extensively at AsciiDoctor and it looks great on a per-topic basis. I'm ready to recommend it, with the understanding that we'll need some sort of wrapper for hundreds of topics we have to create a documentation system with site-wide search and various navigation options. I've been looking at AsciiBinder, which looks very promising, but there's not much "noise" about it online, and the documentation is very sparse. The concept makes perfect sense and is appealing, but I'm leery about recommending that doesn't seem to be used very widely yet. Can anyone comment on AsciiBinder and/or suggest alternatives we could use to package a large set of .adoc topics into a system with fast search? Ideally, we'd be able to come close to replicating our current content (www.splicemachine.com). Thanks in advance, Gary Hillerson |
I don't work on AsciiBinder, but it is used very heavily with OpenShift [1]. Chances are there isn't much noise is because the guys that built it haven't made much noise about it :) I can't really comment about the sparseness of the docs, but it was probably something along the lines of the typical OSS project: Hey, it works, great! Put it out there! It's been working great for the OpenShift team though. On Thu, Sep 22, 2016 at 3:56 PM, ghillerson [via Asciidoctor :: Discussion] <[hidden email]> wrote: I'm a tech writer in the process of finding open source documentation tools to replace our use of MadCap Flare's single source tech writing software. We (Splice Machine) recently went Open Source, and need to transform our documentation into an Open Source system that developers can update and modify. |
Yeah, I looked at the OpenShift docs, and was impressed enough to want to use Asciibinder, but there's not enough info out there for me to understand how to do the things I want to do, like control navigation and search usage and appearance. Thanks, G On Thu, Sep 22, 2016 at 3:51 PM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
|
I think some of the asciibinder guys watch this list, if you don't mind waiting a couple of days to see if they respond, if not I'll ping them via internal email and see if they can respond. On Thu, Sep 22, 2016 at 4:58 PM, ghillerson [via Asciidoctor :: Discussion] <[hidden email]> wrote:
|
To create a whole website with navigation and so on with asciidoc you are best of using some sort of static site generator. The asciidoctor website as well as the Jenkins website do that and are open source. https://github.com/jenkins-infra/jenkins.io https://github.com/asciidoctor/asciidoctor.org You can also use Jekyll with asciidoc support. https://jekyllrb.com/ https://github.com/asciidoctor/jekyll-asciidoc I am sure there are lot of other options... e.g. the Nexus Repository Manager documentation has a custom built setup (its a lot older than asciidoctor and related tools). https://github.com/sonatype/nexus-book Hth Manfred LightGuardjp [via Asciidoctor :: Discussion] wrote on 2016-09-22 16:03:
Manfred Moser
http://www.simpligility.com |
Awestruct, middleman, and jbake are all good solutions as well. Full disclosure, I maintain (when I have time, which is fleeting) awestruct.
On Thursday, September 22, 2016, simpligility [via Asciidoctor :: Discussion] <[hidden email]> wrote:
-- Sent from Gmail Mobile |
Free forum by Nabble | Edit this page |