Manual Writing Tools? 139
Saulo Achkar writes "I've been recently assigned the task to rewrite the user's manual to a piece of relative complex software. Today, the existent manual used was developed with reStructuredText, a very nice piece of software; unfortunately, we're not able to create classes or templates for things like similar interfaces (that share the same functions), which means we need to write more code and that means more editing. XML formats aren't very friendly to code or edit in, either. What kind of techniques or tools are there to make writing manuals a bit friendlier and faster?"
Lawyers (Score:5, Funny)
Re:Lawyers (Score:1, Funny)
Just a suggestion... (Score:3, Informative)
Re:Just a suggestion... (Score:1, Funny)
You're both wrong. (Score:3, Funny)
He asked for "Manual," not "Automatic," writing tools. You should be recommending pencils, pens, and mechanical typewriters.
Re:Just a suggestion... (Score:2)
But, I'm not sure what output forms you need... SGML? manpages?
(Is there a link on the reply-to-a-comment page that takes me to the m
Your #1 site for quality editorial work! (Score:3, Funny)
in other news, sarcasm is the lowest form of humor.
Re:Your #1 site for quality editorial work! (Score:5, Funny)
Re:Your #1 site for quality editorial work! (Score:3, Informative)
Re:Your #1 site for quality editorial work! (Score:2)
Re:Your #1 site for quality editorial work! (Score:2)
Re:Your #1 site for quality editorial work! (Score:2)
All the major news sites do it. Why now Slashdot?
Re:Your #1 site for quality editorial work! (Score:2)
And on that note, I hope Editors can edit their articles to fix stuff like that.
Damn send button.
Grumble.
"Manual" you say? (Score:5, Interesting)
(thought I was going to be getting a pen discussion until I read past the headline)
Re:"Manual" you say? (Score:2)
Me, too. I was so disappointed. I would have enjoyed a discussion of the wide variety of freehand hard-copy editng implements. But I suppose that's cause I'm sick in the head. Then again, that there exists a sufficient number of people interested in the actual topic of the article does not speak well for general sanity, either.
Re:"Manual" you say? (Score:3, Interesting)
Re:"Manual" you say? (Score:3, Interesting)
Re:"Manual" you say? (Score:2)
Re:"Manual" you say? (Score:3, Funny)
Re:"Manual" you say? (Score:4, Interesting)
I'm definitely an anachronism when it comes to writing. I really enjoy writing letters: with a real pen, in longhand, on fancy stationery, to be sent by postal mail. I know a lot of people who lament the loss of grammar and spelling that the age of instant messages has brought upon us. In addition to those, I lament the loss of penmanship and the "human" factor that the word processor has wrought.
Re:"Manual" you say? (Score:2)
Erm... did somebody with a mod point just admit to not reading past the headline? Heh.
Re:"Manual" you say? (Score:2)
...which were invented by a Brazilian, iirc. Biro?
[OT] Nope. Hungarian-Argentine. (Score:2, Informative)
The wristwatch was invented by Alberto Santos Dumont (of "not-quite-first heavier-than-air flight" fame and "first to circle Eiffel Tower in a dirigible ballon" fame), a Brasilian.
Re:"Manual" you say? (Score:2)
I've never got on well with ballpoint pens.
Re:"Manual" you say? (Score:4, Funny)
Re:"Manual" you say? (Score:2)
Pencils and Pens (Score:2)
Back when I was in school and taking lots of notes (I take rather copious notes), I thought it would be nice to be able to erase things instead of just cross them out, but I could never find a mechanical pencil that wrote as easily as a pen. Even with
Re:Pencils and Pens (Score:4, Informative)
Re:Pencils and Pens (Score:2)
--Michael
Manual Writting Tools? (Score:5, Funny)
"Manual Writting Tool"? (Score:3, Funny)
By the way, I'm aware that this is going to look odd once the editor notices the mis-spelling of the headline to the article.
A spelling checker, for one (Score:3, Interesting)
I'd suggest a spelling checker. It would catch things like "Manual Writting Tools?".
Today, the existent manual used was developed with reStructuredText, a very nice piece of software; unfortunately, we're not able to create classes or templates for things like similar interfaces (that share the same functions), which means we need to write more code and that means more editing.
Also, consider physically removing the semicolon from your keyboard. Between the giggles over the misspelled title and the confusion of the above sentence, I have no idea what this article is about.
Seriously, if you want to write something that people will *read*, you've got to keep the human audience in mind -- even if you're just writing program-level documentation. Unless your only goal is to produce a sheaf of paper for the Sarbanes-Oxley [wikipedia.org] auditors, you want your document to be useful for the poor guy who gets stuck debugging the app when the lead programmer gets run over by a bus.
Re:A spelling checker, for one (Score:1)
Re:A spelling checker, for one (Score:1, Insightful)
Re:A spelling checker, for one (Score:3, Informative)
Today, the existent manual used was developed with reStructuredText, a very nice piece of software; unfortunately, we're not able to create classes or templates for things like similar interfaces (that share the same functions), which means we need to write more code and that means more editing.
The use of "existent" in the above sentence is awkward, and the parentheses are unnecessary and confusing, but the semicolon is used properly. It would have been acceptable (and probably less confusing) to break
Re:A spelling checker, for one (Score:2, Interesting)
Writing good English is just as much a skill as writing good C# or Java. Indeed, you can't just say "good English", as the style matters too... good novel writing, tech docs, journalism, and academic writing are all different styles that must be learnt, and some people are better at one style than others.
Regarding tools, the one that keeps being mentioned as being the best for tech writing is FrameMaker. There is a caveat: it takes time and skill to
Re:A spelling checker, for one (Score:2)
This is the second day in a row that some one has made this lovely if unintentional joke.
~ Anders
Re:A spelling checker, for one (Score:2)
Re:A spelling checker, for one (Score:3, Informative)
Re:A spelling checker, for one (Score:2)
Parent touches on a good point. No offense meant to original poster; but, if this post is any judge of your writing it might be wise to consider hiring a professional technical writer... at least an editor. No offense meant, but your english could use a little polish.
It's a significant investment to rewr
Re:A spelling checker, for one (Score:2)
Did the OP say the document would be in English?
Re:A spelling checker, for one (Score:2)
That was a bad assumption on my part.
XML! (Score:3, Informative)
Re:XML! (Score:2)
Wikis, LaTeX (Score:3, Informative)
I personally compose most of my documentation in LaTeX. But then, I makes use of equations & leverage "legacy" documentation. Most newer projects which don't have math would be well-advised to choose an XML-based format. DocBook and other projects tend to use pdfTeX as a
Re:XML! (Score:2)
ConTeXt (Score:2)
Re:XML! (Score:2)
It sort of depends on your perspective. If I was a programmer with an extant, well-involved userbase, and I didn't have a lot of time or resources for documentation, I'd probably just throw up a wiki and edit it when people had questions. This would work especially well if I weren't highly concerned with the quality and consistency of the docs.
With that last part I'm not saying that unprofessional material is a necessary consequence of a wiki, just that if I had to hand something off to my boss or a print
How about Word? (Score:2, Insightful)
Re:How about Word? (Score:5, Informative)
I use LaTeX for almost everything these days. I can't stand using finicky, annoying WYSIWYG word processors anymore. LaTeX is simply a better way.
Re:How about Word? (Score:2)
You must have a lot of experience in it. I have a question for you. How do you turn on automatic word wrapping in a tabular block?
Re:How about Word? (Score:2)
How do you turn on automatic word wrapping in a tabular block?
You define the column as a p, followed by the width in braces; for example, p{1.25in}.
Lamport's LaTeX: A Document Preparation Manual [informit.com] still has one of the best summaries of basic LaTeX commands. For math, Gratzer's Math into LaTeX [springer.com] is an excellent book. Kopka and Daly's Guide to LaTeX [informit.com] is also well spoken of.
Gratzer also has a new book, The LaTeX Book [springer.com], in preparation.
And, of course, there's lots of free documentation [tug.org], as well.
Re:How about Word? (Score:2)
LaTeX may be better than Word, but better than any WYSIWYG word processor? I find that hard to believe. Try using a real WYSIWYG application like FrameMaker. All the consistency of LaTeX, plus a GUI that actually helps you instead of getting in the way.
Re: (Score:2)
Re:How about Word? (Score:2)
On the website for LyX, I find this comment: " Support for writing documents in most European languages" - most? So LyX (or LaTeX) has language limitations as well?
Fortunately, many product manuals can do without Sanskrit and consonant charts.
As for the 'only one language' dig: wrong. We've produced loads of multilanguage manuals.
LaTeX has its
Re: (Score:2)
Re:How about Word? (Score:2)
For all languages supported by Frame, the hyphenation was definitely correct. Ligatures we usually don't bother with. We produce manuals, not novels or typesetting showcases.
If the language isn't supported by Frame, we don't use Frame to produce the book. After 10 years of producing manuals, I can count the number of times that has happened on one hand.
Re: (Score:2)
some ideas... (Score:5, Informative)
Something similar is a program called RoboHelp (from Macromedia now, I think? They've been bought out at least once). It was very similar to Help and Manual in core concept, only a lot more complex, and a lot more expensive.
If you DON'T need Windows Help files, I personally like using LaTeX and Texinfo (from GNU). These are both great for making PDF; Texinfo makes pretty good HTML by default, and LaTeX can be converted into at least decent HTML. I've written a fair bit of documentation for the GNU Project using Texinfo; it seemed kind of "bleh" to me at first, but after a while I got to where I liked it. (And yes, at least Texinfo CAN be converted into Windows Help files of some sort, but I have yet to see this process really work well, at least for what I needed out of it.)
Re:some ideas... (Score:2)
Copywrite for the Mac... (Score:2)
LaTeX (Score:4, Insightful)
Re:LaTeX (Score:5, Informative)
Lyx is a good frontend for Latex too. Its no subsitute for writing it by hand, but then again, there is no subsitute for Latex.
What do you need that OpenOffice doesn't provide? (Score:4, Informative)
Honestly, if you want ease of use, felxibility and power, I strongly suggest using Open Office 2 and the features it provides, such as indexing, data source linking, DB frontends and Forms, etc. Otherwise - if you are a Browser oriented shop - just use one of the countless wikis or - if you all dig the command line and your favorite editors - continue using XML (Docbook or whatever) but beef up your editors with XML plugins, extensions and macros. It's not that difficult, is it?
OpenOffice DocBook (Score:2)
Elsewhere, I plugged DocBookWiki & there are many other fine programs for working with DocBook without getting your hands _TOO_ dirty. However, I thought I'd also mention that OO.o has passable filters [openoffice.org] to import and export DocBook. They aren't perfect, but they beat the MS Word HTML filters.
Re:What do you need that OpenOffice doesn't provid (Score:2, Informative)
I have been a longtime user of LaTeX http://www.latex-project.org/ [latex-project.org] and have found TeXnicCentre http://www.toolscenter.org/ [toolscenter.org] to be a nice front end for LaTeX. I have tried word-processors, but haven't really played with OO.org long enough to understand the sectioning and styles feature. Now, I recently re-stumbled over LyX http://www.lyx.org/ [lyx.org]
I
Writting - not what you think (Score:5, Informative)
Quit ragging on the guy (Score:2)
Re:Quit ragging on the guy (Score:1)
[Hijack] New topic: favorite pens and pencils (Score:2)
Re:[Hijack] New topic: favorite pens and pencils (Score:2)
40s, but Office Depot still makes them? They sound great in theory, writes like a pen, erasable
like a pencil (and not like an erasable pen).
Alas, it is hard to find good writing instruments (Score:2)
All true geeks also do work not in some cheap spiral notebook, nor some hoity-toity Moleskine, but
Use another person1 (Score:1)
Some ideas (Score:4, Informative)
LaTeX [lyx.org] (I'm pretty sure this is available for Linux & Windows too)
Mellel [mellel.com], which has some very good reviews
Manuscript [www.iol.ie]
Which may not be as full-featured.
Possible Tools (Score:2, Informative)
If you're going to create online documentation, you might consider Adobe RoboHelp if you want to create Help easily. Anyone with experience using
Re:Possible Tools (Score:2)
If you want/need to provide a Word file, use Mif2Go.
Technique Depends On Target Audience (Score:1)
Being a geek, I usually don't need manuals, but on the few occasions hell had a cold front go through, I tended to gravitate toward manuals that read more like FAQs.
YMM
Digital had a neat pattern (Score:3, Insightful)
In the days before OO programming your quality of work was often measured by the quality of your code comments and intelligent use of white space. Readability was seen as one of the requirements for maintainability. Good data structures and clean algorithms followed from that.
Have you ever noticed that code flows better when you can describe what you're trying to do in English first? It's kind of like learning to communicate well with yourself. We used to start with the program comments, in English, then fill in the blanks with code. It worked.
Mind mapping... (Score:2)
I can honestly say it has beaten my previous forays with Restructured Text, HTML, Open Office, etc. into a cocked hat.
Give it a try...
Re:Mind mapping... (Score:2)
I, too, am a big fan of mind mapping and am familiar with different mind mapping applications although not the one that you reference. I find mind mapping to be great for organizing ideas. It is sort of an outline on steroids. However, I don't see how mind mapping is very helpful in presenting rectilinear information. How do you use this product to present a table of information?
Re:Mind mapping... (Score:2)
I started with Freemind but that didn't have notes and didn't export to MS Word very well and that was the main feature I was loo
single source publishing (Score:2, Interesting)
LaTeX? (Score:5, Informative)
I worked in some or other (more or less) Linux shops ever since and now and then, when we buy some product/solution we can clearly see, that some people are still using LaTeX, CVS and similar tools. And I can still see that the documentation looks better and cleaner that the crappy Word "paintings" distilled to PDF we receive with some other software. Sure, you can get the same effects with word processors, if you know them well enough, but I just like my documentation system doing things for me, it's bad enough that I have to write it
Robert
Re:LaTeX? (Score:2)
PDF is ideal for reviewing: the reviewer can add comments to the PDF, and the writer can easily integrate multiple comment sets into a single P
Re:LaTeX? (Score:2)
At the time I was running docs repo we used CVS. There are multitude of graphical clients for all platforms. People responsible for documentation's correctness just had to review recent changes (via graphical tools comparing versions side-by-side, with changes highlited), correct Engrish and check in new version.
Saves lots of time.
Robert
We need more info, but here you go.... (Score:4, Insightful)
However, as a tech writer with years of experience, if you don't know much about writing or structuring manuals, I would probably default to the defacto FrameMaker package. It supports Docbook, unstructured and structured (SGML and XML) tagging, and it fairly easy to get going with. If you outgrow it's functionality, you can buy one of many packages for macro editing and automation of repetitive tasks. Adobe has a free program to help you do some of these things, but it's very similar to coding C and may be a bit overkill.
As a last resort (and if you have access to people who know how to create or modify a DTD for your use), you could buy a package such as Stylus Studio for editing code and creating XLST files for automating tasks and formatting the document. Unless you have experience, this will be overwhelming.
If you need online help, well, you'll probably use RoboHelp like most everyone else.
As far as any more advice than recommending the software packages, I think we really need to know the scope of this project (length of book, what type of information is involved, how much of the book is tabular data vs. instructional data, etc). Personally, I have about 5 different software packages at my disposal and use a each on a case by case basis depending on use.
Lyx Editor and LaTeX (Score:3, Interesting)
A Solution (Score:2)
I use LyX for input, and LaTex for the hard stuff. Seems to work out ok...
YMMV
Ratboy
M4 + anything (Score:2)
I recommended LaTeX earlier, but it has one drawback in comparision to reStructuredText -- it cannot easily output different formats, basically just DVI (later convertible to PS) and PDF. rST on the other hand, while able to produce HTML, SGML, PDF, even LaTeX and other file formats, lacks any macro/language extension capabilities.
But you can process rST documents, like any other text files, with generic preprocessor like M4 [wikipedia.org] to achiev
Re:M4 + anything (Score:3, Informative)
Re:M4 + anything (Score:2)
Yeah, sure... First, I did write, that you can generate PS and PDF from LaTeX, you've just cut it. And second: go, convert to HTML, RTF, WordPerfect any decent LaTeX document with custom macros, styles etc.
You see, I do use LaTeX daily, did manage huge documentation re
It Depends (Score:2)
FrameMaker is a good choice. It was designed specifically for producing large manuals. Unlike Word, it does a good job of separating content from layout, meaning you can concentrate on writing stuff instead of having to fiddle with layout issues. Its main drawback is limited support of non-Western languages. If you need to tr
WYSIWYG XML Editors (Score:2)
It is not rocket science.
Kupu, an open source WYSIWYG XHTML editor that you can run from your web browser can be found here: http://kupu.oscom.org/ [oscom.org]
WRITTING? (Score:2)
I wouldn't dream of writing a large document in anything other than LaTeX; the learning curve may be a bit steep but once you're up to speed you'll be amazed and thankful for the gobs of work the system will save you. Plus you can use whatever text editor you're most comfortable with; also, the format lends itself greatly to use of collaboration and revision control tools which will simplify your work even further.
Re:WRITTING? (Score:2)
I wouldn't dream of writing a large document in anything other than LaTeX; the learning curve may be a bit steep but once you're up to speed you'll be amazed and thankful for the gobs of work the system will save you.
I like Latex and use it for some projects, but the language itself is very cludgy and dated. You have to use hacks to insert graphics or even color text. Now these hacks are very well known and explained, but it is still a huge pain. It also is problematic if your project ever becomes large
Professional Help (Score:3, Informative)
Planning and writing good, maintainable documentation is not a really simple task. I'd really recommend you find a contractor with real experience to build a workflow to meet your needs. It will probably save you money in the long run. Assuming that is not an option, you can use many of the same techniques you do for coding. Write out a specification for your toolset. What platforms need to be able to edit the docs? What formats do you need to output? Do you need to reuse content? Do you need conditional text for multiple releases (like rebranded OEM versions). What level of training will the writers and editors have? Do you need spelling and grammar checkers? Will multiple people be collaborating on it and do you need versioning? How long will it be? Will it include a large number of graphics? Are their compliance requirements from the government, partners, or handicapped accessibility?
Once these criteria are determined you can evaluate tools. For some jobs OpenOffice or even MSWord is appropriate. For others, Framemaker+Webworks, InDesign, or Quark would be better. For still others Latex or just a plain old XML editor is ideal. Then there are more integrated solutions like AuthorIT. There are a lot of people who devote their careers to understanding these tools and workflows. Most of the tools have demo versions or are free. The defacto standard in the industry is Framemaker, which is a pretty conservative bet for any project and very "middle of the road." It only works properly on Windows, so you might need to buy a dedicated box for it in some environments.
Once you have built a workflow around some tools, the job of maintaining the documentation becomes much easier. Again, I highly recommend you hire a pro to set it up, otherwise you may end up doing it all over again as you run into tool limitations and realize you failed to follow industry best practices and now have to migrate everything or customize every tool you use.
FrameMaker (Score:2)
Check out the free evaluation.
What I don't like about FrameMaker? Adobe dropped the Linux port, after a successfull beta test, due to lack of interest... sigh...
YARIFTRW (
Unable to create classes or templates.... (Score:2)
Re:Use another person (Score:3, Insightful)
Re:Use another person (Score:1)