: What's the best text editor for a technical reference manual? It is my first time writing tech manuals and I don't know what to use. Some people recommend me LATEX but I think it's too complex.

Vote Up Vote Down

Word is acceptable for short documents. Make sure to set up paragraph styles and always use them (no manual formatting).

When your manual exceeds 50 pages or you have layout requirements beyond the basics, Word becomes increasingly troublesome: instability and document corruption are common in large documents.
You'll also run into trouble with the way Word handles images: you have to use linked images to keep your file size reasonable, but then you have to repair all the links when you move the Word file to a different directory.

For large documents, use e.g. FrameMaker, which is designed for technical documentation and much better at it than Word.

Whatever solution you choose: for printing at a print shop, always create a PDF on your workstation, check if the layout is correct and then take the PDF to the printshop. Never assume the printshop can handle your source document.

(0)

Vote Up Vote Down

LATEX isn't a text editor, it is (broadly defined) a markup language. The alternatives would be things like markdown, asciidoc, docbook, or simply using HTML directly, in tandem with your favorite plain text editor.

Docbook and HTML are "heavyweight" markup languages (you need a tag for every paragraph, etc), whereas markdown and asciidoc are lighter and paragraph breaks can be entered just by pressing return twice.

The question then becomes whether and how you intend to publish in print format. If your copy shop can accept any PDF then you can use whatever you want so long as it can convert to a PDF or to HTML (which you can then convert to PDF using a web browser and PDF print driver). Some publishers or print shops may have specific preferences for how you provide your document to them.

(0)

Vote Up Vote Down

Having taken the considerable amount of time that it takes to learn how to use DTP software (most recently when I had the job of laying out a magazine) and knowing what results you can achieve, I would definitely recommend you just use a word processor such as Word or Open Office. What you are doing doesn't need extremely precise control over layout, including things like letter spacing. In fact, you want each page to look the same. If you use styles in a word processor, you can achieve consistency of look with little effort.

When you want to take your work to a print shop, export it as a pdf. Most printers will work with common word processing formats, but with a pdf you can be sure of exactly what it will look like. Things like type of printer won't change how it looks on the page.

(0)

Vote Up Vote Down

I think MS Word and Open Office would be the obvious candidates. MS Word pretty much dominates the market. Open Office is there for people who just want to rebel against Microsoft.

I'd need a very good reason to use anything else, as to function in a Western business, government, or academic environment these days you pretty much have to use MS Word at some point. Why bother learning something else in addition unless it offers specific advantages?

MS Word allows you to create "styles" that you can use to distinguish your main text from special types of text, like block quotes or examples or, as in your case, code snippets. People do this all the time: I did it myself for my database book. I think your time would be far better spent learning how to do this in MS Word than searching for some alternative word processing software that might possibly make it easier to do it. If you're smart enough to write a technical reference manual, you should be able to learn how to do this in MS Word in, what, half an hour? An hour? :-)

Personally I think Word's handling of embedded images is rather awkward and clumsy. But it works, and the idea of learning a whole new word processor, and having to convert files back and forth any time I want to share them with others, doesn't seem worth the effort to me. Maybe if I was creating a document with many images that had to be laid out in complex ways, I'd start searching for something else.

(0)

Vote Up Vote Down

For Mac, take a look at BBEdit. In particular, it has fully supported GREP search-and-replace functionality. There's an e-book that can be bought with the BBEdit product, which is highly recommended because it provides usage examples for the GREP functionality.

For Windows, try Notepad+. In addition to the base product, there are any number of plug-ins that can be installed to support your workflows.

On further thought, consider using Adobe InDesign. It has the layout tools that (it sounds like) you need, and it gives you greater control for managing large documents. This will also open the door for more advanced writing with other Adobe products, such as (structured) FrameMaker and RoboHelp.

I couldn't really suggest MSWord, unless you knew that you were going to constrain your work to smaller documents.

(0)