Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Manual Writing Tools?

Cliff posted more than 8 years ago | from the from-code-to-printed-man-pages dept.

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?"

cancel ×

139 comments

Sorry! There are no comments related to the filter you selected.

Lawyers (5, Funny)

albalbo (33890) | more than 8 years ago | (#15564855)

I get my lawyers to do it; they're my writting machines.

Re:Lawyers (1, Funny)

Anonymous Coward | more than 8 years ago | (#15564966)

I was expecting a joke about habeas corpus, but I suppose that would be rather anachronistic.

Re:Lawyers (0)

Anonymous Coward | more than 8 years ago | (#15568254)

This just demonstrates that a manual writing tool should include a spell checker.

Just a suggestion... (2, Informative)

DrMorris (156226) | more than 8 years ago | (#15564868)

... what about sticking with reST and using m4 or other macro package to do repeated tasks?

Re:Just a suggestion... (1, Funny)

Anonymous Coward | more than 8 years ago | (#15565250)

No, no, you get it all wrong! You are supposed to suggest writing everything in DocBook, using Emacs or Vim. Using efficient plain-text is so 70s. Modern people use Java-based XML-processing-frameworks that use 156MB JVM-space to process a 500 byte README.

You're both wrong. (3, Funny)

Anonymous Coward | more than 8 years ago | (#15566495)

He asked for "Manual," not "Automatic," writing tools. You should be recommending pencils, pens, and mechanical typewriters.

Re:Just a suggestion... (1)

orangesquid (79734) | more than 8 years ago | (#15568374)

If I were to write or rewrite a user manual, I'd find some way to do it in LaTeX, since that allows all sorts of template and macro forms, and can be output as PDF, HTML, and other things, and can be edited in a plain text editor. There's also lots of packages out there already (see CTAN) that might be helpful by having templates and such that might be close to what you need.

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 main article? Before the redesign, I thought there might have been, but I don't think there's anything now *pout*)

Your #1 site for quality editorial work! (2, Funny)

bunions (970377) | more than 8 years ago | (#15564869)

writting!

in other news, sarcasm is the lowest form of humor.

Re:Your #1 site for quality editorial work! (4, Funny)

DrMorris (156226) | more than 8 years ago | (#15564893)

Well, that clearly tells us that this guy's looking for "writting" system that at least supports spell checking...

Re:Your #1 site for quality editorial work! (2, Informative)

slashflood (697891) | more than 8 years ago | (#15565343)

I hope you realized that this guy is from Brazil. Maybe his first language isn't English and he is writing the documentation in Portuguese?

Re:Your #1 site for quality editorial work! (1)

bunions (970377) | more than 8 years ago | (#15565471)

I'm pretty sure Cliff's first language is English.

Re:Your #1 site for quality editorial work! (1)

HardCase (14757) | more than 8 years ago | (#15566554)

He'll fix it in the dupe.

Re:Your #1 site for quality editorial work! (1)

azav (469988) | more than 8 years ago | (#15566227)

All editors who post articles should be required to simply run spell check on their posts.

All the major news sites do it. Why now Slashdot?

Re:Your #1 site for quality editorial work! (1)

azav (469988) | more than 8 years ago | (#15566253)

Um, what I meant to type was "Why not Slashdot?"

And on that note, I hope Editors can edit their articles to fix stuff like that.

Damn send button.

Grumble.

"Manual" you say? (5, Interesting)

Fallingcow (213461) | more than 8 years ago | (#15564870)

I like ballpoint pens.

(thought I was going to be getting a pen discussion until I read past the headline)

Re:"Manual" you say? (1)

Elemenope (905108) | more than 8 years ago | (#15564901)

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? (0)

Anonymous Coward | more than 8 years ago | (#15564993)

Ditto. I like pens and typewriters. A discussion on them would have been interesting.

~Tia

Re:"Manual" you say? (2, Interesting)

creimer (824291) | more than 8 years ago | (#15565034)

Yeah. I missed the old Pilot felt tip pens of yesteryear. Although recently Pilot came out with a "liquid ink" (not gel ink) pen using a plastic tip that's writes similiar to the old felt tips.

Re:"Manual" you say? (2, Interesting)

martinultima (832468) | more than 8 years ago | (#15565126)

Personally, I'd say my favorite Pilot pens are the Precise ones – you know, the nice solid tube-shaped ones that you can get in a four-pack at Wal-Mart for just a couple bucks. Although my absolute favorite pen is probably one which my dad and I turned on his lathe – it's a bit chipped, because it was the first pen either of us tried turning using a "fancy" pen blank and not regular wood, but it's really neat looking, and I'm right now using it to write a novel (I've been writing the entire thing by hand, one section at a time, just randomly ordering things around – after I've got enough sections together I'll write some stuff to connect them all and then type everything up at once. A lot easier to edit that way; I once did write a complete novel, but it's horrible and I'm probably never going to publish it...)

Well, so much for staying on topic!

Re:"Manual" you say? (2, Funny)

SEWilco (27983) | more than 8 years ago | (#15566736)

Ditto. I like pens and typewriters.
Ah, there's nothing like the fresh smell from a ditto machine.

Re:"Manual" you say? (3, Interesting)

GospelHead821 (466923) | more than 8 years ago | (#15565191)

That was my first thought as well. A while back, I got into several lengthy discussions about handwriting implements. I am quite fond of the Pilot G2 pen. The ink smears a little bit, but the colours are vibrant, the cartridges are easy to obtain, and they are also used in the Dr. Grip series of pens, which are very comfortable and stylish. They're also the only gel ink cartridge I've ever used that doesn't dry up in the tip and clog the pen if you don't use it for a few weeks.

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? (1)

NanoGator (522640) | more than 8 years ago | (#15565461)

"(thought I was going to be getting a pen discussion until I read past the headline) (Score:3, Interesting):

Erm... did somebody with a mod point just admit to not reading past the headline? Heh.

Re:"Manual" you say? (1)

Nefarious Wheel (628136) | more than 8 years ago | (#15565465)

I like ballpoint pens.

...which were invented by a Brazilian, iirc. Biro?

Re:"Manual" you say? (1)

exp(pi*sqrt(163)) (613870) | more than 8 years ago | (#15565590)

I bought my favourite pen (for writing) in the UK. It's a cartridge pen (you know, the type with an actual nib) that cost UKP 1.99 from WH Smith. It's astonishing. My fanciest pen is a beautiful Edgar Allen Poe Mont Blanc that cost about $1000. It's beautiful to look at, but my $4 pen from WH Smith writes better.

I've never got on well with ballpoint pens.

Re:"Manual" you say? (0)

Anonymous Coward | more than 8 years ago | (#15566490)

I prefer fountain pens. Specifically, the PILOT V-pen, which is disposable.

It writes better and lasts longer than the Parker fountain pens I have.

Re:"Manual" you say? (1)

(1+-sqrt(5))*(2**-1) (868173) | more than 8 years ago | (#15566512)

My fanciest pen is a beautiful Edgar Allen Poe Mont Blanc that cost about $1000.
I always shy away from those garish signatures; a good Meisterstück [londonluggage.com] does the trick (possibly the Hommage à Chopin), which, in solid Sterling [londonluggage.com] , will still break the kilobuck.

Re:"Manual" you say? (4, Funny)

Anonymous Coward | more than 8 years ago | (#15565606)

I'll take 'penis mightier' for 500

Re:"Manual" you say? (1)

CastrTroy (595695) | more than 8 years ago | (#15565742)

I actually prefer pencils (the mechanical kind). That along with a good vinyl erase is the best writing instrument. You can correct your mistakes, and you don't ever have to sharpen the pencil. And they maintain a relatively consistent sharpness.

Pencils and Pens (1)

Kadin2048 (468275) | more than 8 years ago | (#15566732)

I tried to like mechanical pencils, I really did.

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 .05mm leads, it always seemed like I would have to constantly rotate the pencil to avoid the line thickness changing and keep it sharp. Maybe it has something to do with the way I hold my writing instruments (at an angle). Also, I never managed to find a pencil lead soft enough or dark enough to give the kind of contrast you can get from pigment-based (or even good dye-based) pen inks.

It sure would be nice, though, if someone could come up with an erasable pen that wasn't a crummy ballpoint. I can't think of how you would do it, maybe something like the trick "disappearing inks" that used to be sold as gags. Even if it required a solution that had to be put on like white-out, but wasn't as obvious, that would be pretty neat.

I eventually just settled on using Pilot P-700 disposable rolling ball pens, and then white-out pens to cover the occasional mistake. Not quite as good as erasing, though.

If any other pen addicts have found a pencil that they thought was a substitute for pens, I'd be interested in hearing others' experiences.

Re:Pencils and Pens (3, Informative)

CastrTroy (595695) | more than 8 years ago | (#15568132)

I don't think I've ever seen a 0.05 mm lead. maybe .5 mm, which is what I use, although I think they still .3 mm also. As far as the sharpness goes, yes, it does require the pencil be rotated every so often , but that can be solved by just learning to get a rhythm, and rotating it before it gets to the point of being too thick. This also helps the contrast problem, as it usually shows up darker when you're writing on the sharp edge. You definitely won't get anything as good as a pen, but it's a trade off. I'd take the erasability of a pencil any day, over having to futz with whiteout, or having to cross things out. I find that I actually like the resistence given by a pencil, and find pens to be too smooth. I guess it's all just personal preference, but I don't really understand the appeal of pens, except in circumstances when you don't want something to be erased, like when you sign your name to something.

Manual Writting Tools? (4, Funny)

ozbird (127571) | more than 8 years ago | (#15564883)

If you find a good spellchecker, let the Slashdot editors know... (Manual Writing Tools.)

"Manual Writting Tool"? (2, Funny)

ctid (449118) | more than 8 years ago | (#15564911)

Is this some l33t haX0r way of saying, "lawyer"?

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.

Re:"Manual Writting Tool"? (0)

Anonymous Coward | more than 8 years ago | (#15565009)

Yes, I'm sure the editor is going to notice. It's always been obvious that they pay careful attention to the front page, through their scrupulously correct grammar and spelling, and lack of dupes.

Use another person (0, Flamebait)

JohnWilliams (781097) | more than 8 years ago | (#15564912)

Given that you make both a spelling mistake and a grammatical error in the first 100 words or so of this post ("Writting tools" for a "relative complex" piece of software, I think the best tool you can use is another person, prefarably one who can write!

Re:Use another person (0)

Anonymous Coward | more than 8 years ago | (#15565055)

And what better place to go looking for tools than slashdot?

Re:Use another person (2, Insightful)

bwhaley (410361) | more than 8 years ago | (#15565455)

Yes. Preferably someone who can write. ;)

Re:Use another person (1)

JohnWilliams (781097) | more than 8 years ago | (#15565610)

Someone? If you mean to imply that I should have written that instead of "one", please reconsider. Both "one" and "someone" are grammatically correct and consistent with current usage. However I'm not perfect of course: I mis-spelled "preferably" !

A spelling checker, for one (2, Interesting)

RobertB-DC (622190) | more than 8 years ago | (#15564919)

What kind of techniques or tools are there to make writing manuals a bit friendlier and faster?

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 (1)

The Mighty Buzzard (878441) | more than 8 years ago | (#15565051)

Easy to read or not, you've got to give the guy his due for actually knowing how to use a semi-colon properly; it's a quickly fading skill.

Re:A spelling checker, for one (1, Insightful)

Anonymous Coward | more than 8 years ago | (#15565108)

I am guessing that the guy who wrote the coherent lead probably did not write the illiterate headline.

Re:A spelling checker, for one (2, Informative)

Wonko42 (29194) | more than 8 years ago | (#15565061)

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 the sentence into two sentences, but that doesn't mean the semicolon was misused.

Re:A spelling checker, for one (2, Interesting)

rivimey (534327) | more than 8 years ago | (#15565099)

I would agree with the need to bear your audience in mind.

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 set up properly. However, once that is done it can be used well by authors who aren't also geeks!

If you feel tempted by DocBook or one of the other XML based systems, I've found the XML Mind XML Editor decent, but with less flexibility than Frame.

MS Word should be ignored -- it is too unconstrained and too buggy for large documents (>100 pages).

Some people really like LaTeX, and it is indeed good even for large documents, but only if (a) your authors are prepared to learn it and (b) your desired output formats are supported. It is supported by Windows as well as Unix, and there are GUI front-ends (by default it is batch processed).

HTH,

Re:A spelling checker, for one (1)

aconbere (802137) | more than 8 years ago | (#15565174)

Writting English well is just as much a skill ...

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 (1)

Eideewt (603267) | more than 8 years ago | (#15565406)

Is there something wrong with the phrase "writing good English?" "Writing English good," is wrong of course, but good is a good adjective, isn't it?

Re:A spelling checker, for one (0)

Anonymous Coward | more than 8 years ago | (#15565635)

Yes, there was nothing wrong with that sentence. I suggest setting your threshold to block everyone with a UID higher than 750,000.

Re:A spelling checker, for one (2, Informative)

DragonWriter (970822) | more than 8 years ago | (#15565338)

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.
While the sentence you quoted may have been confusing, the semicolon was properly used, and shouldn't be blamed for any confusion.

Re:A spelling checker, for one (-1, Offtopic)

Anonymous Coward | more than 8 years ago | (#15565459)

Yeah, thanks for making the same joke after about 200 other people have already made it.

I suppose I can't expect much from a fag who links to the DIXIE CHICKS in his sig...and the subscriber * next to your name is like a proud badge of idiocy.

Re:A spelling checker, for one (1)

Gribflex (177733) | more than 8 years ago | (#15565878)

>> 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.

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 rewrite an entire user manual. Your company (and you) would be wise to invest the little bit extra to hire someone to do it right the first time. It will make a world of difference.

A Life Insurance Policy, for one (0)

Anonymous Coward | more than 8 years ago | (#15566961)

"Unless your only goal is to produce a sheaf of paper for the Sarbanes-Oxley 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."

*note to self* Do NOT become a programmer. Apparently being run over by a bus is one of the job hazards.

XML! (2, Informative)

Noksagt (69097) | more than 8 years ago | (#15564991)

XML formats aren't very friendly to code or edit in, either
You're doing it wrong. There are a number of excellent XML or general text editors that do the job. There are even online collaboration tools, such as DocBookWiki [sourceforge.net] . Most importantly, it is easy to get programmatically-generated documentation in XML & also easy to reformat XML into your destination formats.

Re:XML! (1)

martinultima (832468) | more than 8 years ago | (#15565088)

Personally, I tend to like just a regular old wiki for documentation – for example, most of the documentation for Ultima Linux is on a MediaWiki site [ultimalinux.com] . Although this might not be the best way if you need printed documentation, because of the fundamental differences between a Web site and a wiki. Of course, if the primary method of providing documentation is going to be printed, I'd say learn LaTeX – it's really not very hard at all, and it tends to be very good for technical documentation because it (1) handles all the formatting for you so you just have to do the actual content, (2) has some very, very powerful typesetting capabilities if you need advanced features like tables, mathemetical symbols, etc., and (3) is almost trivially easy to learn, at least as far as I'm concerned.

Wikis, LaTeX (2, Informative)

Noksagt (69097) | more than 8 years ago | (#15565203)

I am a dev on projects that use wikis for documentation. They are great for collaboration, but rather proor at providing a polished website and, as you say, horrendous at printed documentation. They don't tend to be well organized.

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 backend for PDF generation, so has many of the same benefits you get from using LaTeX directly. The processors for writing (x)html seem to be more evolved than the equivalents for LaTeX: They're faster, easier, and look better.

Re:XML! (1)

Procyon101 (61366) | more than 8 years ago | (#15565326)

However, DocBook has the capability to write the documentation once and, via xslt, give you a nice website, print form and help file for an application.

ConTeXt (1)

Noksagt (69097) | more than 8 years ago | (#15565417)

As before:I think XML is the best-fit for most projects & LaTeX is appropriate for those projects which already have legacy documentation or share documentation with papers submitted to journals. However, I neglected to give a shout out to ConTeXt. ConTeXt also uses the TeX backend to produce beautiful results, but is a bit easier to program in. [contextgarden.net]

Re:XML! (1)

happyemoticon (543015) | more than 8 years ago | (#15565914)

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 printer I'd probably want something without stub articles and with everything well-edited. I suspect, with so many hands involved, that editing it to the point where it was printable would quickly become a full-time job. Also, printed media is better with a beginning, middle, end, a table of contents and an index. I'm not sure how you'd turn the hypertext wiki into something linear like a manual.

I'm saying this as somebody who works with a few different wikis on a daily basis. The ones I use are great. But I'm also saying it as a technical writer, and if I were going to put my name on something and tell my boss with a smile, "This is what you're paying me for," I'd probably hand him a docbook xml file, not a link to an internal company wiki.

Harun Yahya !? (1)

Cycnus (162186) | more than 8 years ago | (#15566243)

Wow, an open source project that supports Harun Yahya (look at the top right of the page).
Harun Yahya is a "thinker" that promotes all kinds of completely bogus pseudo-scientific garbage in the support of Islam.
Have a look at their main site, it's the Muslim equivalent of intelligent design.
Now an open source project that clearly supports/sponsors such nonsense is an issue to me.

That everyone is free to think what he/she wants and be as wrong as delusional as they wish is their problem, but when an organised entity that is non-political and non-religious in nature explicitly supports objectionable views, is it moral to support that entity and give credence to their views by using their products and services, be they free and open?

Re:XML! (1)

ChaoticChowder (971057) | more than 8 years ago | (#15566287)

I agree... I would personally use DocBook and Vex. It's relatively easy to setup and because it is based on Eclipse, you could write a plugin or ant file to generate all the output formats you want. If you want to do a web site, you could even set it up to deploy to your webserver too.

How about Word? (2, Insightful)

JeffHunt (129508) | more than 8 years ago | (#15565000)

Or OpenOffice? Word processors are good at processing, uhm, words... you know.

Re:How about Word? (4, Informative)

Penguin Programmer (241752) | more than 8 years ago | (#15565178)

They're good at processing words, but _terrible_ at typesetting. Another poster mentioned LaTeX, which would also be my recommendation. It's great for technical writing, you _know_ that your whole document will look consistent (no need to go through and change _every_ diagram or tab stop individually, just change them for the whole docuemnt) and it's easy for a future publisher of the manual to change its look to match how the want to print it.

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? (0)

Anonymous Coward | more than 8 years ago | (#15566154)

"I can't stand using finicky, annoying WYSIWYG word processors anymore. LaTeX is simply a better way."

Maybe for a technical writer. But why the fuck would, say, a college student or secretary have any use for LaTeX?

Re:How about Word? (1)

yamla (136560) | more than 8 years ago | (#15566454)

College students have to follow specific layout guidelines, something Word is astoundingly bad at.

Re:How about Word? (1)

Bob_Geldof (887321) | more than 8 years ago | (#15566549)

LaTeX is absolutely indispensable for (Applied) Mathematicians. I know of no other way to get equations to "just work". And yes, I do it on my macbook too.

some ideas... (5, Informative)

tjr (908724) | more than 8 years ago | (#15565008)

In my previous job, I wrote a lot of documentation using a program called Help and Manual [helpandmanual.com] . I can't say that I thought it was wonderful, but it was functional, especially if you need to make Windows Help files.

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... (1)

3waygeek (58990) | more than 8 years ago | (#15567909)

I've used Help & Manual, too -- it's unbeatable for the price if you need to do CHM or HLP formats.

Copywrite for the Mac... (1)

creimer (824291) | more than 8 years ago | (#15565017)

If you're working with or just writing plain text, the best editor I been using is Copywrite [bartastechnologies.com] for the Mac. Besides handling files on a per project basis, the full screen mode is great with a slider to readjust the text size on the fly.

LaTeX (4, Insightful)

calumtdalek (983493) | more than 8 years ago | (#15565026)

LaTeX is awesome for technical writing.

Re:LaTeX (5, Informative)

bunbuntheminilop (935594) | more than 8 years ago | (#15565056)

++

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? (3, Informative)

Qbertino (265505) | more than 8 years ago | (#15565048)

Or more precisely: What do you need that OpenOffice 2 doesn't provide? You're obviously not into Docbook, because that would be the obvious choice for freaks who want to do their editing in VI/Emacs/Nedit/Jedit. The Blender [blender.org] folks did that with the Blender 2.3 manual. And they hated it. Now they're back to open source word processing.
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 (1)

Noksagt (69097) | more than 8 years ago | (#15565435)

You're obviously not into Docbook, because that would be the obvious choice for freaks who want to do their editing in VI/Emacs/Nedit/Jedit.
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 (2, Informative)

sgarg (197658) | more than 8 years ago | (#15566794)

Just started out with Vex http://vex.sourceforge.net/ [sourceforge.net] . It looks to be a pretty neat XML editor, based on Eclipse, with the DocBook DTD http://www.docbook.org/ [docbook.org] built in.

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 think I will stick with LyX/LaTeX till I understand DocBook better.

On a side note, I came across NaturalDocs (http://www.naturaldocs.org/) yesterday. It looks to be a neat way to generate documentation without messing up the whole thing with tags.

Now, it would be a nice idea to take all these diverse ideas and combine them together into a single tool that can work as a driver for various formats (somthing like GCC, which can compile multiple languages). So, you need to know 1 tool, which can parse reST, NaturalDocs, Doxygen etc. You know, the great unified theory of text processing ...

Writting - not what you think (5, Informative)

Anonymous Coward | more than 8 years ago | (#15565071)

Yeah - you need to make writs... A technical term that sounds like it's a misspelling (mispelling :D ) of writing but is actually for creating writs. In fact, the English "write" is really just an evolution of a word "to writ". Similar to how "God be with you" became "goodbye" and "fare thee well" became "farewell", the verb "write" came from the middle English "writ". In fact, "writ" and "red" share the same etymology. It's actually from the Saxon phrase "writ and blood", which means a contract and originates from the custom of bleeding to purge illness. The modern corruption of this is "written in blood". Contracts were never "written in blood" but this sounds plausible to our modern ears than "writ and blood." BTW, the British word "bloody" (as in, "we had a bloody good time") came not from "blood" (sanguina), but from "By Our Lady" (I.e., the Virgin Mary). Anyhoo, the "writtings" is similar to being served - i.e., "The tax evader was writted with a notice posted on his door."

Re:Writting - not what you think (1)

design.sound (913825) | more than 8 years ago | (#15568735)

Admit it, you made all that up, didn't you.

Quit ragging on the guy (1)

/dev/trash (182850) | more than 8 years ago | (#15565135)

+1 for not saying TASKED, when assigned is what is meant.

Re:Quit ragging on the guy (1)

Bastard of Subhumani (827601) | more than 8 years ago | (#15565240)

Sadly, that's somewhat offset by the -97 for putting "to rewrite" where it should be "of rewriting".

Manual writting tool? (1)

Cainjustcain (782020) | more than 8 years ago | (#15565164)

Like a pencil?

[Hijack] New topic: favorite pens and pencils (1)

Wise Dragon (71071) | more than 8 years ago | (#15565195)

I read this as Manual Writing tools as in pens and pencils. A topic dear to our hearts. So what are your favorite writing tools of the manual variety? I had a zebra telescoping pen but I found it fell apart in my pocket a lot. I've switched to the Fischer space pen and I'm loving it so far.

Re:[Hijack] New topic: favorite pens and pencils (1)

belg4mit (152620) | more than 8 years ago | (#15565308)

I've been trying to track down some graphite ink pens. Apparently these were all the rage in the
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).

Re:[Hijack] New topic: favorite pens and pencils (0)

Anonymous Coward | more than 8 years ago | (#15565504)

My latest favorite is the Pilot P500. .5mm, very fine, clean lines and good ink.

Unfortunately, they seem to have become hard to find. The next time I see any I plan to make a large stockpile purchase.

Alas, it is hard to find good writing instruments (1)

sirwired (27582) | more than 8 years ago | (#15565653)

My personal favorite is an old Koh-I-Noor 0.5mm Rapidomatic Engineer's Pencil. Nothing beats the knurled Aluminum grip for multi-hour writing sessions. Unfortunately, they shallowed out the knurling some in '97 or '98, which makes it too slippery for multi-hour writing sessions. I've tried a Berol substitute, but the barrel is too heavy, round (instead of hexagonal), and I don't like the rubberized coating.

All true geeks also do work not in some cheap spiral notebook, nor some hoity-toity Moleskine, but in an "Engineer's Computation Pad", available in college bookstores everywhere. Low-eyestrain green tint, high-quality bond, and graph lines on the back that show through enough for easy diagramming, but not so much they show up in a scan or Xerox.

I know that fountain pens are a classic fine writing instrument, but they are tough to use for lefties, and involve using absorbent writing paper (to keep my left hand from smearing the ink), instead of whatever is handy. Plus, I make mistakes.

SirWired

How's Your Portuguese???? (0, Flamebait)

Anonymous Coward | more than 8 years ago | (#15565228)

All you pompous twats that are quick to complain about his "poor writing skills" have failed to notice that the requestor is Brazilian! English is not his native tongue and the manuals that he plans to write are probably not English either.

So, having harangued the man because of your own ignorance I must ask; How is your Portuguese? I'm willing to bet that your Portuguese is no where near as good as his English.

Pesaroso, escrita == writing

Use another person1 (1)

JohnWilliams (781097) | more than 8 years ago | (#15565259)

Given that you make both a spelling mistake and a grammatical error in the first 100 words or so of this post ("Writting tools" for a "relative complex" piece of software, I think the best tool you can use is another person, preferably one who can write!

Learn to write (-1, Flamebait)

Anonymous Coward | more than 8 years ago | (#15565289)

Learn to write, you arsefucking wog-dog.

Some ideas (3, Informative)

Phat_Tony (661117) | more than 8 years ago | (#15565332)

I don't know what all the features are that you're looking for, and I don't know if you work on a Mac, or which of the following programs have PC equivalents, but here are some programs which I think are scriptable, template-using, auto-formatting word-processors aimed at managing, editing, and producing books, manuals, and other similar projects:

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 (2, Informative)

Anonymous Coward | more than 8 years ago | (#15565333)

If you're going to write printed manuals, you might consider using Adobe FrameMaker, a tool designed to handle lengthy documents. (Even Microsoft uses FrameMaker instead of Word for some of its third-party texts.) With some add-ons, FrameMaker can also produce HTML and online Help. In addition, FrameMaker offers a structured mode that allows writers to work in XML.

If you're going to create online documentation, you might consider Adobe RoboHelp if you want to create Help easily. Anyone with experience using an HTML editor such as Dreamweaver or FrontPage will find RoboHelp friendly to use. For a more robust, XML-based solution, you might consider MadCap Flare. In addition to generating a variety of Help formats, both RoboHelp and Flare can produce printed manuals. (Flare's printed documents turn out better than RoboHelp's do, in my opinion.)

As for writing methodology, your best bet is to enroll in a technical writing course at your local university. If you take the course seriously and have an excellent teacher, you can learn much about writing clearly, concisely, and simply.

DECdocument (0)

Anonymous Coward | more than 8 years ago | (#15565341)

I use DECdocument for such things. If it's good enough for the OpenVMS documentation set (quite probably the largest documentation set out there), it is good enough for me. The best part is you'll need an OpenVMS system to run it!

Technique Depends On Target Audience (1)

thepropain (851312) | more than 8 years ago | (#15565433)

At the company I work at, I'd say 90-95% of our manuals consist of screenshots with arrows, and everything's broken up into the smallest possible steps. Our typical users range from "computer-ally ignorant" to "technophobic". The few users who have actually bothered to read the manuals tell us they're the best manuals they've ever read.

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.

YMMV.

Digital had a neat pattern (2, Insightful)

Nefarious Wheel (628136) | more than 8 years ago | (#15565442)

Digital Equipment Corp was known for their well laid out, informative and easy to use VAX/VMS manuals (cue old "three rooms of heaven" jokes). They were highly automated. They used Edit/TPU templates for coding that enforced carefully structured comments in program code, followed by a program that stripped the comments from programs written that way and structured them into a book, with appropriate fonts and styles. What followed was simply editing the output of that program and printing it, a much easier job than writing the entire document from scratch.

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... (1)

tyroneking (258793) | more than 8 years ago | (#15565489)

...specifically with Mindjet's MindManager software (Windows and MacOS only I'm afraid) has made all my documentation work much easier over the past few years. Add Text notes to the map nodes and you can export to HTML, MS Word (gulp...), MS PowerPoint (double gulp...) and text.
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...

single source publishing (2, Interesting)

goodminton (825605) | more than 8 years ago | (#15565490)

If you're going to produce your manual in both print and online form, AND you might possibly want to re-use some of the manual content for things like brochures and presentations, I'd go with a single-source publishing [wikipedia.org] system like AuthorIT [wikipedia.org] . Single-source publishing was developed specifically for software projects and it allows you to create documentation in many different formats. It also allows you to reuse content across documents, which saves time and reduces inconsistencies caused by redundant content being recreated for each document. It ain't free but I've used AuthorIT for several years now and I'll never go back to producing documentation using Word or OpenOffice.

LaTeX? (4, Informative)

Gadzinka (256729) | more than 8 years ago | (#15565586)

If you used reStructuredText and liked it, but found it lacking in some features, why don't you try LaTeX [wikipedia.org] ? I used to manage a rather large documentation for middle size (~50 people) company in LaTeX and found it being plaintext-based a blessing -- all the developers could use all the free revision control systems for documentation as well, without a problem.

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

What the heck is "writting"?? (0)

Anonymous Coward | more than 8 years ago | (#15565616)

Use your spell checker. :) :) :)

We need more info, but here you go.... (3, Insightful)

ProppaT (557551) | more than 8 years ago | (#15565847)

First of all, we have no idea what format the book is to be in (print, pdf, windows help file, etc). Each different format requires different software/knowledge. Without this information, it's pretty hard to recommend anything.

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 (3, Interesting)

imagineit (618047) | more than 8 years ago | (#15565994)

I was also searching for a better way to create technical documenation and stumbled upon Lyx http://www.lyx.org/ [lyx.org] . It is a WYSISYM (What You See Is What You Mean) editor that gives you the power of LaTeX with a GUI frontend. You will find it truly amazing how fast you can write when you are not concerned with the layout of your text.

nice topic (1)

joshetc (955226) | more than 8 years ago | (#15566000)

Hmm upon reading the topic I was under the impression you were interested in tools for "manually" writing something. Upon further inspection it seems you are looking for tools to write a manual.

Whats wrong with MS word or OOo?

A Solution (1)

ratboy666 (104074) | more than 8 years ago | (#15566451)

"Manual Writting" -- that's good.

I use LyX for input, and LaTex for the hard stuff. Seems to work out ok...

YMMV

Ratboy

M4 + anything (1)

Gadzinka (256729) | more than 8 years ago | (#15566952)

One thing that came to my mind after some decent sleep is M4 preprocessor.

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 achieve that goal. Couple it with make and you have consistent, extensible documentation system without a learning curve ;)

Robert

Look at asciidoc (1)

lpointal (953132) | more than 8 years ago | (#15567665)

It is not too much different than reStructuredText, it gives readable ascii content, but it target producing html and... DocBook. For Docbook, there is a system of redefinable tags (I have not used them, but I've read about them in the doc).

You can find more informations at http://www.methods.co.nz/asciidoc/ [methods.co.nz] .

A+
Laurent.

It Depends (1)

hcdejong (561314) | more than 8 years ago | (#15567698)

What's the scope and scale of the manual? If it's a complex piece of software, the manual is probably more than a few pages, which rules out Word. Word tends to choke on long documents.

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 translate your documents to Thai or Arabic, FrameMaker isn't the best choice. With products like Webworks ePublisher or Robohelp, you can publish to various HTML and other online formats, including context sensitive help.

There are other packages geared towards producing large manuals. AuthorIT is one I can recommend. Unlike FrmaeMaker, it supports Unicode. It's built on top of a database, meaning you have document management facilities which come in handy if you're writing lots of related manuals, reusing text etc. It also offers export to Word, PDF and online formats.

Others I haven't worked with.
Some have recommended LaTeX. My experience with this is limited. You really need a graphical front end to flatten the learning curve. Changing the layout of your output isn't straightforward either.
I don't know how well OpenOffice handles long documents. But the way it's built to mimic Word makes me wary. Does it have a way to consistently apply styles?

From the wording of Saulo's post, I guess he's a developer. No offence, but few developers are good writers. For one thing, many developers (and engineers in general) have a hard time putting themselves in the customer's shoes. This leads to manuals that omit lots of information that's obvious to the engineer, but not to the customer. You may be better off hiring a technical writer instead.

(I write manuals for a living. I mainly use FrameMaker and AuthorIT. )

SmartDocs - Using MS Word to Author? (0)

Anonymous Coward | more than 8 years ago | (#15568299)

If you are thinking about writing technical manuals, I recently saw a demo of something coming out from ThirtySix Software (http://www.thirtysix.net/ [thirtysix.net] ) which might help. It seems to give you the ability to do some structured-authoring type things (reusable text, conditional text, etc.) in Microsoft Word. Might be worth checking it out...

WYSIWYG XML Editors (1)

Lodragandraoidh (639696) | more than 8 years ago | (#15569071)

There are WYSIWYG xml editors out there - so you don't have to delve down into the ugly details unless you really want to -- and you can modify the online look via CSS, and use other filters to generate PDF, and other formats as needed.

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]
Load More Comments
Slashdot Login

Need an Account?

Forgot your password?

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>