> Hello again. :-) > > I'm glad my comments are of value. I'm quite enjoying > the OpenSolaris forum model, being able to give back > and add value. :-)
[mo] Yes, this is great, feel free to start new threads here for other doc topics you might have on your mind. > > Yes, I think a PDF with annotations would do the > trick. The issue I refered to earlier was PowerPoint > (or equivalent) presentations with just the > bare-bones slides turned into PDF's, and all of the > critical explanatory monologue during the > presentation being lost. Some of the LISA course > materials are a good example of what to do: the top > of each page is the slide as displayed by the > instructor, while the rest of each page is a more > detailed explanation if required, maybe pointers to > more resources, etc. That is, the kind of things the > instructor discusses while you're looking at the > three bullet points. I think the important aspect I'm > driving at is the associated notes, without which > many PDF'd slide shows become valueless. [mo] This same point about cross-referencing the detailed style guide came up in an offline conversation today also, so +1 for this idea. We talked about a style quick start that has pointers to the details in the Big style guide, so we'll keep that in mind. > > My big difficulty with DocBook was not the writing > (never even got much time to produce a document). [mo] Uhg, that is exactly what we hope to avoid. :( My > problem was confusion over the plethora of tools, > what I really needed (there seemed to be several > layers, and multiple tool choices per layer), the > order to install them, and which worked well > together. Things may have changed since then (this > was well over 1.5 years ago), but at the time, there > was no guidance as to: > > 1) "You need these three 'pieces'. These three > e products work well together, as do those three. > Pick either set." There was no clear distinction > between how many layers there were to getting to a > workable state. Indeed, it wasn't always clear which > layer a specific tool fit into. [mo] Understood, I agree that we need to make some recommendation about a *set* of tools to use. DocBook has been mentioned by the community in earlier threads and we got some comments from Frank yesterday about Solbook, so the discussion is still ongoing. > 2) "Due to dependencies, you'll need to install the > e layers in this order: x, then y, then z. For > recommended tool set A, that means first Ed, then > Harry, then Frank." Good point, hopefully we can determine a limited set of choices and be sure to provide branching instructions for each set. > 3) "That gives you your toolset. Now, to produce a > a DocBook, start by using Ed to type up a document > (and, perhaps, here's at guide to the codes used for > formatting). Save it. Call Harry using these > parameters and switches. That creates harry.doc. Now > call Frank using this switch. When Frank is finished > running, you'll see frank.docbook. That's your > DocBook output. View using Sally. Rinse, lather, > repeat." That Sally, she's got eagle eyes :) > > Now, mind you, things may have changed significantly > since I wandered through the moors in the fog, > tripping over dead branches. I've heard this same concern about DocBook and making it simple for the community to get up and running, so another +1. Also, I am admittedly > better at the actual writing, and "oh, this detail is > missing" part than I am at actually creating > fully-formatted, customer-ready output (I'm a vi kind > of guy ;-), but if I can do the former in a toolset > that easily creates the latter from the input, then > I'm more than willing to put in the extra up-front > work. (And yes, I still write my HTML in vi.) I think > everyone will be happier, though, knowing the above > details up front, and not wasting time figuring out, > "how do I get there from here?" > > I hope that clarifies, and that I'm not being overly > obtuse. This is great input to the process we'll create for doc collaboration! Thanks for the detailed descriptions ...and the humor :) As I say, there may have been significant > leaps made since I last explored DocBook creation. > I'm just not wanting to spend a day Googling, > especially if it's only to find out, "oh, here's the > one tool we use, and it takes care of everything for > you! Life is much simpler using this." :-) I try to prevent all-day-googling and cut/pasting everywhere I can. I feel like there will be two pieces coming out of this now: -a short version of editorial style information that points back to the big style guide -a slide show/tutorial for getting tools set up that also points back to the 'Writing for DTD' chapter (still to be written) in the big style guide Thanks and keep it coming! -Michelle > > Thanks again. > > Rainer This message posted from opensolaris.org
