What tool are you using for documentation?

Discussions
#1

Which tool are you using to create a manual for your software? (I guess this probably applies mainly for who is selling a downloadable piece of software).

I’m currently using help and manual and you can check here how the manual look http://www.phraseexpander.com/help/

The problem is that it’s not very seo friendy and uses frames!

I’d like to create something similar to the help manual of Helpscout

How can I create something like that that is more SEO friendly? My manual is pretty long and creating pages one by one in wordpress would be quite painful.

Thanks.
Andrea

#2

I use Manula: http://www.manula.com

I’m content with it.

#3

Hi Steve,

Thanks for the info. I was leaning toward a desktop solution (with no recurring fees) but Manula could potentially be an interesting option if I can quickly import my Help & Manual file.
I’ll test it out.

I see you are doing Mac software. What’s the standard way to create help manuals on the Mac. Web manual?

Thanks a lot.
Andrea

#4

The previously standard way to create help manuals for Mac software would be to create a “Apple Help Book” within your App bundle: https://developer.apple.com/library/mac/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html

It’s a set of HTML pages in a well-defined folder structure.

But these days I feel that most products simply link from the Help menu to an online user guide. Apps made by Apple still use Apple Help.

#5

Thanks for the info Steve.

#6

Hi. I have started using trello as the source for my documentation. The nice thing is that I can really structure the content well in a way that makes sense to describe partially complex scenarios. It also forces you to make real good headings, which can help you in longtail SEO. When the trello doc is pretty much clean I get the JSON of the trello board and convert it to markdown.

I love markdown. Markdown keeps your content very clean. So a trello board represents an article in the igumbi documentation. To do the markdown conversion I have this small `ruby script (GIST).
I have just recently started with this process, but I am really liking it. Especially as you can invite others to contribute to your trello board, so the documentation will evolve without too much pain (I hope)

See some examples of the support articles (in German): “Anzahlung Verwalten” or a lengthy one without screenshots, still prepping them ): “Channel Manager mit igumbi Hotelsoftware verbinden”

For screenshots/images my CMS has a tag, so I can reference them in the Markdown Texts I enter in trello.

The nice thing is that I can later repurpose the Markdown Files to compile a PDF Version using Marked (A Mac Markdown tool.

1 Like
#7

I think you’ll need to balance things out. If you want something SEO friendly then a plug in for WordPress would be better. Yes, creating page by page on is going to be painful but one piece of the puzzle with SEO is having lots of pages with long content. Below a couple of plug ins for WordPress

http://themeforest.net/item/knowhow-responsive-wordpress-theme/3356732

#8

@joseacta Thanks for pointing this out. One of the main problem I have is that my software is a downloadable version and when a new major is released I need to update a number of pages and tracking all this with wordpress is a nightmare (and I also need to be able to generate a PDF file). I fear that working directly in wordpress is not an option.

#9

One of the benefits of working with markdown, as the primary master publishing format, is that you can use a framework like leanpub ( https://leanpub.com/help/manual) to create a “Book” or PDF or E-Book later if you want to.

#10

I have used Doxygen for many years. Most people who know the tool think of it as being about documenting code with comments in headers.

However, Doxygen includes an expanded Markdown as well as DOT (Graphviz). Using DOT lets you create simple box and arrow diagrams directly in your docs, using plain text. These render and layout automatically.

So using Doxygen can be more like writing in a Wiki and because both the diagrams and (Markdown) content are plain text, work very well with version control.

#11

Andrea,

Several years ago we were communicating regarding our help tool Dr.Explain. Since then we we had several important releases and I invite you and other Bootstrappers to look at the recent release at http://www.drexplain.com/

You can check some online manual samples made in our tool at http://www.drexplain.com/help_authoring_samples/
There are no frames, no problems with SEO. Our own manual made in our tool receives many visits from search engines.

I’ll be glad to answer any question here or privately.

#12

Thanks Dennis.

I remember your tool but I’d see the cost of switching to another solution too high. I think we’ll either use Manula or check the new Help&Manual v.6 as it looks like they have improved a number of things. It’s probably the solution with less friction for us.
Thanks.

1 Like
#13

I had this same question a couple of months ago when I started writing the documentation for my software. After experimenting with and researching a few options, I recently settled with Sphinx (http://sphinx-doc.org/). I am really pleased with it.

  • It is free.
  • It maintains the plain readability of Markdown to a very good extent. But, it has many more constructs than a typical Markdown dialect when you need them.
  • On the surface, it may appear that it is geared towards documenting software written in Python. This made me ignore it in my first round of search. But, upon closer look, it turned out that it is very for writing documents in general.