On Mon, Apr 25, 2005 at 11:47:37PM -0500, Patrick McNamara wrote: > I agree that the focus should be on content, not form. However, I can > say from experience that form can sell content. One of our target > audiences is the corporate world. Given two documents with the exact > same contents where one is the dump of a wiki and the other is a > nicely and professionally laid out document with nice formatting, I > can tell you exactly which will be picked and which will be rejected.
What "level" of quality are you thinking of when you say "nicely and professionally laid out document with nice formatting"? Is any content massaging is involved, or can a (hypothetical) perfect stylesheet language alone do the job? Here are some levels that come to mind, in increasing order of niceness. - Raw markup - Plain text - Unadorned HTML - Wiki printout, with navigational clutter included - Typical word processor output - Wiki printout, with navigational clutter removed - Competently-produced word processor output - LaTeX defaults - Expertly-produced word processor output - Expert (La)TeX - Quark Xpress/FrameMaker/whatever-is-used-I-don't-really-know-the-name Some great thing about markup: automated conversion to most of these higher levels, production/edition with a variety of tools, easy versioning, focus on content, alternative styles. So use it. Notice how subtly I dodge the question of which markup language to use. On second thought, don't notice it. I'm being subtle, remember? > As far as wikis go, I've worked with them before and they can be > incredibly powerful tools. However they are not designed for creating > publishable documents. You can't go download the contents of a wiki > and print it out on the office printer for later reference. Ok, so > actually you can, but it's not easy or pretty. DokuWiki's export_html mode looks nice. > I would also prefer, if at all possible, to keep the requirement, > specs, and any other docs in the same repository as all the other > stuff. It makes it easier for all involved to be able to go one place > and get anything you might need. Perhaps you can keep the "important", publishable content in a SVN (&c.) repository, alongside all the sources, etc. Whenever any such document is updated in the repository, update the Wiki to mirror. (Assuming your wiki doesn't use some inaccessible database format--- DokuWiki uses the filesystem--- a humble script can do this for you.) Mark these pages read-only on the Wiki, and include links to alternate formats (also auto-generated by your scripts). Sticky bits: images/diagrams, conversion to Wiki markup language, desire to use the Wiki to edit the publishable content, integrating with the Wiki's revision display. > I must admit I'm still at a loss. For the time being, I would suggest > we start using the wiki. It is a very useful dumping ground for ideas > and I don't want use to get stuck trying to figure out how we are > going to produce something as "simple" as documentation. :) In a project for which I was team lead (I am no longer), I recommended using DokuWiki to develop and collect all project documents, on the grounds that it's a centralized repository, its HTML output is nice, its markup language is simple and relatively powerful, its interface is good, it tracks changes, it supports tables, and its markup (which the Web server will export) can potentially be translated to XML/DocBook/ LaTeX for higher-quality output. Sounds reasonable... It worked well, up until the project manager dictated that we cease using it in favor of MS-Word and MS-FrontPage. Now we have to manually track and merge changes, and boy is it painful. (We're not allowed to use any revision control system besides MS-SourceSafe, which is not yet available to us.) Don't put your foot in that particular bear trap. You must have automated revision tracking. You must use plain-text source files wherever possible. You must support outputting to both HTML and PS/PDF. And you must not require your readers to deal with unstandardized file formats. Good luck coordinating documentation. -- Andy Goth + [EMAIL PROTECTED] + http://ioioio.net/ _______________________________________________ Open-graphics mailing list [email protected] http://lists.duskglow.com/mailman/listinfo/open-graphics List service provided by Duskglow Consulting, LLC (www.duskglow.com)
