2

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.

I basically need a text editor that let me:

  • Type latin characters (I will write it in Spanish)
  • Type code (with some style and in a textbox)
  • Insert some images (not many and w/b only)
  • Easy to print it in a copy shop

Any ideas?

Thanks in advance!

  • 1
    Microsoft Word? – user5645 Apr 27 '15 at 9:28
  • Although it is a very professional software, I would have to create a template or something for writing pieces of code, I am pretty sure that there has to be another software for this kind of purposes – SpongePablo Apr 27 '15 at 9:41
  • Every text editor requires that you define your styles. Word is the easiest editor, if you don't want to learn to use another. Here's how you insert code in Word: stackoverflow.com/questions/387453/… – user5645 Apr 27 '15 at 10:48
  • 3
    Are you asking about an editor or a source format? LaTeX, for example, can be edited in any text editor, same as HTML. Word, on the other hand, has formatting built in; it's not just a text editor. – Monica Cellio Apr 28 '15 at 19:18
6

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.

  • 2
    LibreOffice (which spun off of Open Office due to ~politics~, taking most of the developers with it) is generally considered the best office software for those of use who want to rebel against MIcrosoft. – evilsoup Apr 28 '15 at 12:34
5

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.

1

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.

  • 3
    I don't know anything about BBEdit. But Notepad++ is not a good choice for writing a book or article. I use it every day to edit programs and HTML pages, but it has no features to lay out pages, insert images, use alternate styles for different blocks of text, etc. Notepad++ is a programmer's editor, not a word processing product. – Jay Apr 27 '15 at 13:43
  • +1 for a useful post from a new user. But I don't know why you (and other people) say MSWord can't handle large documents. I've never encountered any restrictions. Admittedly, though, I've never tried making a long book that also had lots of graphics. Can you (or someone else) elaborate on that criticism of MSWord? – dmm Apr 28 '15 at 18:46
  • Well, working with large documents (100s of pages), you end up continuously checking for shifts in layout that might occur whilst editing sections. Also spending much time making corrections to headers/footers that, if you have a change in layout, then you're stuck with checking for errors (i.e., changes) in the headers/footers. You're also prone to layout errors if you don't have the correct default printer set (i.e., the WYSIWYG will be incorrect). MSWord is feature-rich, though there are more powerful tools that are easier to manage your documents, such as the ones I mentioned. – Vzzdak Apr 28 '15 at 19:24
1

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.

  • Adobe FrameMaker is indeed the correct answer when Word isn't good enough. – kindall May 18 '15 at 15:54
0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.