Little survey about software manuals

[Ivan_C]

A have a little question for software developers : what software do you use to write the manuals of your applications / plug-ins ?

• LaTeX + an IDE ?
• Word / LibreOffice Writer ?
• Powerpoint / LibreOffice Impress ?
• Desktop Publishing Software like Adobe Indesign ?
• HTML or Markdown to PDF tools ?

I like the idea of LaTeX where you can just write your contents and you can not care too much about the layout, but nothing looks really sexy with it, and I wonder if more modern tools exist to write something like a manual with a minimum effort

[PurpleSunray]

LaTeX + no IDE (TeXworks + Notepad++)

I like the idea of LaTeX where you can just write your contents and you can not care too much about the layout, but nothing looks really sexy with it, and I wonder if more modern tools exist to write something like a manual with a minimum effort

It depends on you how it looks like, it is all configurable^^
Also really nice is the pre-processing - we use it a lot like:

Code: Select all

\IfDefined{ENABLESSL}{
\begin{Option}{OPTION_HTTP_SSL_CA}
	\OptionType{STRING}
	\OptionDescription{Specifies a CA file located at the given path.}
	\OptionRange{UTF-8}
	\OptionDefaultValue{NULL}
\end{CinemoOption}

If you have ENABLESSL defined during build, OPTION_HTTP_SSL_CA is part of the doc. If ENABLESSL is not defined, there is no OPTION_HTTP_SSL_CA on doc.
We use such macros for a lot of stuff, i.e. the name of customer is a \CustomerName.
IMHO that makes LaTeX much more sexy than i.e. Word.
You don't get a generic huge documention pdf, but one that exactly fits to the build config and even has stuff like project name, customer name, build version, ect. pp in it. Makes customers feel special (oh, wow, they created an own documention just for me... no we didn't, it is all LateX macro magic).

[Miles1981]

I've been asked to add manuals in my free plugins, I'll probably use latex because it is then easy to add to the source code repository without storing additional binaries.

[khanyz]

I've been writing manuals for a long time. The system I've used has varied with the situation but version control is always key.

For developers like Tone2, ToneBoosters & Klanghelm, I kept it simple so just LibreOffice. I'd build a template, then write the manual and publish to PDF, using the built in version control.

For my own dev projects, and others, I used markup, usually XML or HTML, and integrated it with the code version control. I had scripts and template configs (CSS like) to compile it into a manual (Text/HTML/PDF/CHM etc.) or integrate it into the program help (resource file).

I usually only wrote the English manual and then had others translate, but it was a fairly painless process if you had a proper template and versioning.

I've always avoided LaTeX as it was an additional format, with no clear advantage for me. Most developers, I worked with, already knew XML/HTML so could understand, proof and approve the raw text. This made the process faster.

More recently, I have been trying Markdown. It makes writing faster, and the raw text easier to read, but I need to convert my scripts/generic template configs over to it.

Also, naming conventions are key to any document management and reuse. I treat it similarly to naming modules/classes in object code. Create a standard for yourself and stick to it. It may cost you time in the short term but you'll gain it in the long.

Taking screenshots during testing can save a lot of time. I include it in test scripts as well as in macro scripts for automation. You can also automate the processing of them, I use Paint Shop Pro scripts.

[stratum]

I couldn't even write a CV with LibreOffice. Initial template looked good, but it quickly turned into a nightmare of formatting problems.
Latex was much better.

[PurpleSunray]

The system I've used has varied with the situation but version control is always key.

+1
One more reasone I like Latex. If a cusomter asks about what has been changed between versions, we can simply build a "red-line" version of the doc. It runs a diff between the versions (python script) where the diff is a new LateX doc, with all changes colored red.

[Zombie Queen]

Adobe InDesign + Photoshop -> PDF. I'm not quite a software developer, but I happen to make few manuals.

[JCJR]

Long ago when print manuals were the thing, first used pagemaker than later quark express which was quite nice. Haven't used either in years.

Photoshop mostly for illustrations. Someday I need to find a good vector graphics program, for diagram-based illustrations, export to photoshop for final polishing.

Though the output would look horrible by modern standards I was real fond of old mac superpaint which had dual layers, a vector layer and a bitmap layer. Have briefly tried various newer vector graphics programs and cad programs (not recently) but lost patience before getting proficient. The workflow just seemed needlessly slow and arcane though am sure it would get better with practice. Superpaint vector graphics were easy to get what I wanted rather quickly with virtually no learning curve.

The company I worked with the last 20 years before retirement, paper manuals were still fairly important. The business manager of the small company was a great guy, old musician like me. He did most of the grunt work assembling and formatting the manuals. During fall and mid-summer crunch times, he probably did a lot more manual writing than business managing. I didn't keep up with how he worked but I think a great deal of it was assembled and formatted in ms word. The guy was very good with ms word. I didn't get along with word very well. Word was OK but somehow annoying.

Manuals were collaborative. Each programmer would write explanations of features he had worked on, including illustrations where needed, and tech support and media guys would write what they knew about, then the biz manager would assemble and proof and format the mess, writing additional copy where needed.

We also had a very bright multi-lingual translator. She was heavily involved in writing the manuals in addition to translating the documentation to some languages and hiring out other translations.

The manuals were also exported to pdf of course.

Also involved was context sensitive popup help system. It was so much fun I can't remember much about it. There was some old-style windows help format, that was encoded using ms word. Use arcane formatting commands in word and then run a command line program that turns it into a help file. Then later on, ms decided that mess was a security risk and quit supporting it in the OS so we switched to html help.

Of course, at least at that time none of the windows help docs or formats were easily possible to use on mac, and all the mac help needed editing anyway, different contol key illustrations and different screenshots. I think we went thru two or three different versions of whatever apple thought was the perfect brilliant way to do help files at whatever whim Steve Jobs happened to be in at the time.

The holy grail would have been some format where the manual and the context sensitive help would be the exact same document, so you don't have to maintain two similar but different files for pc, two different files for mac, and then multiply that by however many different languages. I vaguely recall some companies selling rather high price "holy grail" solutions. We never bought into any, dunno if any are good. I'd guess one might need to be a rocket scientist just to figure out how to operate such a tool.

I recall one time studying up on how hard it might be to index context sensitive help calls, pop up help balloons filled with text snipped out of arbitrary places from the main pdf manual. Which didn't seem possible at that time, or at least not feasible without spending lots of programmer hours on it.

Lately for my own use I use open office which doesn't seem much worse than anything else and its free. The couple of freeware programs I released since retirement, wrote html documentation with png graphics made in photoshop. Just looking for clarity rather than "pro formatting". Another advantage is the same set of files can either be included in the downloaded prohram zip for local viewing, or displayed on a web page. No need to convert the same info into two different display formats (for instance html for web and pdf for download).

However that would probably not be slick enough for commercial product targeted at non-geeks.

[resynthesis]

LaTeX, Emacs, org-mode, AUCTeX. Use them for just about everything text related.

[stian]

We use Help & Manual: http://www.helpandmanual.com/
Very nifty tool if you target multiple documentation formats and platforms.

Best,
Stian

[Guillaume Piolat]

I tested pandoc, wasn't convinced by the input language (ungodly mix of Mardown and latex together).

Got back to LibreOffice which is very fast to make a manual into. The problem is then adding binaries into the repositery.

Ideally I'd like a multilingual Markdown (at the sentence level), versionnable text files, and a PDF compiler that could be a regular command-line. A close solution is LaTeX I guess, though I don't really like the output. I guess some solution exist somewhere, but haven't found.

[xoxos]

scribus doesn't take much of a learning curve for pdf layout. it's a tiny bit fiddly to use (text fields are designed for text entry, cursor can move a bit slow) and the pdfs are often slightly large but = manuals.

[lorcan]

I use asciidoctor (http://asciidoctor.org/), it's a bit like Markdown but much more powerful.
You can use variables and macros, include files, export to html/pdf, style the output with css etc.

[Ivan_C]

Wow thanks for sharing all this information, I'll have a look for all the things you have talked about !

I know already LaTeX since I wrote a PhD thesis with it, and seriously I think it's going to be the last option I'd like to follow there I remember using the windows tools to make CHM files a LONG time ago too, I didn't know it is still possible to do things like that with modern tools allowing scripting.

[dmbaer]

Irrespective of the final delivery format (for me that's usually Word Press for web these days, but PDF is occasionally the target format as well), I write the text of anything even a little lengthy in MS Word. Word does better than anything else I've yet encountered in identifying potentially bad grammar. I find it remarkable that it catches some of the things it does. I would not want to be without it. Even if I'm writing a lengthy forum post, I'll often fire up Word in order to avoid embarrassing errors.

By the way, I wrote this post directly in the forum editor, so if there are mistakes, it's not my fault!