3

I'm creating a booklet on teaching programming through examples and exercises. What's the best software for writing the pages? It'll be code examples, exercise questions and some diagrams.

I'm new to designing and writing an instructional booklet. Would Adobe's InDesign or QuarkXPress be appropriate for this kind of job?

3
  • 2
    I think that syntax highlighting would be quite important even if it is very light and you can do that in indesign cs4+ with Grep styles: rahady.posterous.com/… - indesignsecrets.com/…
    – Joonas
    Jan 25, 2012 at 9:44
  • Thank you Lollero, yes syntax highlighting would be very valuable! Looks like I have to come up with regular expressions for the Ruby code though... kind of a pain.
    – at.
    Jan 25, 2012 at 16:34
  • Recently Quarkxpress developers are putting more attention to users, so take a look at it. version 2017 is coming.
    – London
    Apr 22, 2017 at 23:26

6 Answers 6

3

It's tricky to make a recommendation. You say "booklet", which implies a small project, but I assume if it's successful you won't stop at one. Here's the thing: no matter what software you use, you're faced with a significant investment of time learning to use the application, and from a practical standpoint I consider that a very important consideration. I'm pragmatic. What will get the product out the door at the quality I need in the shortest amount of time is what I will always go with, even if (as has happened) I have to learn a whole new application to get there.

Several other answers here give you some insights. I don't want to detract from them.

Here are my suggestions, with the reasons why, so you can make your own judgment.

  • For authoring the text, use the word processor you're most familiar with. It doesn't matter much what it is, because its sole purpose is to get the text together. The shorter the learning curve, the better. If you're a whiz with a good code editor, that's going to work for you better than Scrivener, Scribus or Word if you have to learn them before you can get up to speed. (If you're already up to speed on LaTeX, you're miles ahead of the curve, but it doesn't sound like you are.)

  • For layout, I would highly recommend InDesign, not because it's the best possible tool (Framemaker or LaTeX would make some tasks simpler, especially if you were going deeply into long textbook authoring), but because it will get the job done and the effective and useful learning resources at your disposal are easily ten times what's out there for other possibilities. InDesign is a fairly steep learning curve, but LaTeX and Framemaker are, frankly, a cliff. The sheer quantity of excellent training resources for InDesign, and the huge and active community that surrounds it, make it my "Editor's Choice" for a newcomer to page layout.

  • GREP styles in InDesign are easy for anyone half-way familiar with regular expressions, and you can build a library of queries and styles based on regex which are portable from project to project. Do them once, and you have them forever.

  • Quark Xpress is a powerful layout program. It's been overtaken by InDesign because it has less support, doesn't have the intensely powerful integration of the Creative Suite, and its training resources are now completely overshadowed by InDesign. I don't personally know anyone who's switched from Quark to ID who would ever switch back.

2
  • I love this answer
    – at.
    Jan 26, 2012 at 3:19
  • Very thorough. And you're right about Quark; I grumbled when I had to switch from PageMaker to Quark, and grumbled again switching to InDesign, but InDesign has quite a few more features, and it's consistently more stable. "It doesn't crash as often as Quark" was pretty much the reason my office (with 15 workstations) made the jump. It takes a while to find the typesetting tools which Quark had front and center; beyond that, there's no reason to go back. Jan 26, 2012 at 11:39
2

Yes, absolutely. Either of those programs will give you complete flexibility over where you put the diagrams and how they're sized, how the text does or doesn't wrap around them, the font and indents of the code sections, headers and footers, how pages break, and so forth.

Word is for writing letters and legal documents, not for page layout. Illustrator may allow you to create diagrams (depending on what they are), but it's vastly easier to do a multi-page document in either InDesign or Quark.

3
  • What about syntax highlighting for the code? Lollero mentioned InDesign's GREP styles, does Quark have a mechanism to do this automatically? Which do you prefer, Quark or InDesign?
    – at.
    Jan 25, 2012 at 16:36
  • I have used both Quark and InDesign extensively. I haven't used the GREP styles although I can see how powerful they are, and I would recommend InDesign on the strength of that alone. I don't believe Quark has anything like that function, but I admit I haven't used it in years, so the most recent version could have it. Jan 25, 2012 at 16:45
  • 1
    A superior way to do syntax highlighting is to use a source code printer like listings to generate the properly typeset code in LaTeX. This can then be used in Quark, InDesign, etc. In addition to LaTeX's usefulness for bulk typesetting (and not just for source code) in document/book publishing, listings supports a ton of different languages and comes with lots of options. It's far preferable to trying to come up with your own GREP styles to parse each language yourself. Jan 25, 2012 at 21:25
2

I truly despise Microsoft Word from a pre-press standpoint, but I have to disagree with the comment above. If you are an advanced user with Microsoft Word it can be a very useful program to create multiple page technical documents. Sometimes I actually prefer to use Microsoft Word based on it's integration with Excel and chart input. I love InDesign/Quark from a design standpoint, but for technical writing I would prefer Microsoft Word. It all depends on your own comfort level with each of the programs. If you have worked in Microsoft Word in the past and are comfortable with your experience level in that program, I would not suggest straying from that if you are creating a very time intensive multi-page document. However if you are not an advanced user of Word then it can't hurt to try a different program since it will take you the same amount of time to stumble through Word as it would to learn Quark or InDesign.

4
  • 1
    what's in the technical document? Does it have multiple graphics? Tint boxes? Any pages which go horizontal rather than vertical? Called-out text boxes? Which go to a second page? An index? Word is not a layout program. You can force it to do all those things, but "force" is the operative word, and the document will be fragile (that is, repeated updates will make it crash easily). Word is meant for heavy, uninterrupted text with minimal graphics. That didn't sound like what the OP was describing. Jan 25, 2012 at 14:54
  • While I disagree strongly with the idea of laying out publications in Word, having used it in for such purposes, I do think that the OP should use Word or {other} to actually compose the editorial portion. InDesign and Quark are at their best when composing publications using already generated components, be it merge-able data files, running story, or graphic elements.
    – horatio
    Jan 25, 2012 at 15:18
  • Each page will mostly contain code examples. The rest of the page will be a little of descriptive text, a question and maybe a diagram. Very seldom will there be a photo of any kind. Tint box? maybe... but not necessary. It's unlikely I'll change orientation of the pages, but possibly that would be helpful in a rare situation. Would also be nice if occasionally parts of a page can flow into a second page.
    – at.
    Jan 25, 2012 at 16:41
  • 3
    The point is that if you are writing the content, then you are probably going to design too early. Michael Bay might start filming before the script is written, but you shouldn't.
    – horatio
    Jan 25, 2012 at 21:02
2

While Indesign or XPress would be decent tools to use.... Actually, for text books and manuals I highly recommend Adobe Framemaker. Few have ever heard of Frammaker but it's been around for many, mnay years. It's specifically designed to handle book content that has a great many internal references and call outs such as technical manuals.

1
  • Hmm.. I'll have to check this out.
    – at.
    Jan 25, 2012 at 19:04
2

I've used an prefer InDesign for book layouts (300+ pages). The Page Masters, Paragraph/Character Styles, and grep styles are pretty easy to use and provide great control of your formatting. I advise setting up your master pages and styles before getting to far on the project to be able to most efficiently apply your formatting.

As Mentioned indesignsecrets is a great resources. So is, layersmagazine and creativepro

1

"What's the best software for writing"

That's a much different question than what the best question for page/document/book layout is.

For writing, it's your personal preference. Whichever word processor gives you the features and flexibility needed to write. As long as it can export into a file format that a page layout software can use, you should be good to go.

As for laying out the book, InDesign is pretty much the standard these days. QuarkXPress can work as well.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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