This is a bit of a niche topic i guess. I’m looking for a tool to document enterprise level software. I’m not referring to code documentation, but rather to documentation to be used by end users.
In the old days I had the pleasure of using word documents, and later with DITA files. Word offers great formatting options, clear change tracking and is widely used, but it not very good in combining multiple documents. DITA’s formatting was acceptable, and supports document maps, but we had to export documents to word in order to clearly present changes for review.
I imagine that to some of you these are all stone age tools and would love to have recommendations for modern tools. I am currently looking at Confluence and Clickhelp, anyone used these?
Confluence is basically a shitty MediaWiki that has some convenient hooks into the rest of the Atlassian stack that can be handy. I mostly hate it.
GitHub Pages are quite solid and easy to use and collaborate with. I’m a big fan, but that’s also because I have embraced Markdown in all things.
Honestly, I still find Google Docs to be the gold standard for pretty much any document collaboration though. Enterprise infrastructure helps (i.e. you already use Google tools) but you don’t even need that. I really love the way they do sharing, revision history, all that. GitHub is probably more “modern” FWIW and as I said Markdown is life, but end-users don’t care about any of that.
As always, the best tool is the one your users will actually use. I find that comes down pretty much to convenience on their end. If it’s an Atlassian shop, probably Confluence (barf) is the way to go, etc.
Lots of great tools to single source with HTML and PDF output. I’ve used it to output everything from Kindle books to Word docs. It has options for DITA, but I haven’t used those. If it looks interesting, I can probably answer questions you might have. I’ve been using it for a few years now.
What output do you want to provide customers? And some details about your current environment might help. Flare is a Windows product, so that might be a blocker. Do you have a current doc set and if you do, what format is it in now?
I use Sphinxdoc. I’ve also looked into markdown books before but never used them.
The advantage of sphinx (and the .rst format it uses) is that it’s all plain text, which means changes can be easily tracked and collaboratively worked on using normal source control tools (i.e. git). This is a million times better than a doc file on a shared drive, or something. Also it means I can use my normal test editor.
Sphinx will output web pages, pdfs, .doc files etc.
For examples of sphinx use, see the official python documentation (on phone, but it’s like https://docs.python.org) and everything hosted on readthedocs.com
We have absolutely nothing setup at the moment. We are very small and new and in the process of building our products. Coming from more established software vendors, I am aware of the pain that documentation issues can cause with clients so I’m trying to get something up and try to avoid problems I used to have to deal with because out documentation tools (word, DITA) were not good enough.
I’m looking for something that will allow us to work on documents collaboratively within the company, and will be easily exposed to clients for review and approval.
We do use google docs but I’m not convinced it’s a good solution. We’ll give it a go, but otherwise I’ll also take a look at the other suggestions here.
We use Robohelp and Google docs. The former has far more tools for source control, different media and the like although I’m not sure how good it is for client review (we don’t do that.) I much prefer Google docs, it’s just far easier to use and share, but I then was thrown in the deep end and had to use Robohelp without any background in any kind of authoring tools.
What is the “technical profiency” of your end users?
We use the Knowledgebase plugin for Wordpress at my job but that is for end users (and content creators) with little to no technical knowledge of HTML etc. and doesn’t have much in terms of versioning in my experience.
Personally I would prefer something like XWiki after having the agonizing experience of using MediaWiki for internal documentation. Though I haven’t tried using it for writing articles it seems like one of the most user friendly and feature rich wiki platforms out there and has support for exporting to multiple file formats.
Finally I want to mention TikiWiki on the recommendation of Joe Armstrong at a conference keynote where he described it as the closest anyone has got to a working implementation of the rules of Project Xanadu. It seems like a weird project to me and I have an irrational distrust of PHP applications but it might work for you.
It is a shift from traditional End User documentation to a specific task mentality. It has analytics built in that can watch what the users are doing to prompt short training vignettes within the application itself.
Looks cool but it won’t cut it in the industry I’m in. We are selling software for financial institutions and these people usually want to see in writing what the software does exactly functionally.
As an output format I still like HTML Help if you make the effort to create a detailed index. It’s an ancient format so is super speedy on modern systems.
