On Monday 21 May 2001 23:05, John Weiss wrote:
> Oh, I listen. ;) Real life, however, intrudes from time to time, and
> I can go for weeks without cleaning up my lyx-box. But when I have
> something to say, I'm hard to shut up! :)
<heh> I know how that goes. Real life can be a major bummer sometimes...:)
> Anyway, both Mike and George should read this entire thing
> thoroughly. My past experiences may save you future aggravation.
Definitely appreciate your input here John. I have seen the differences
between the older documentation (I believe there was an older copy of the
docs in with version of KLyX that I looked at some time ago) and what you
have done with it.
> First, to the tone of the Intro. Yes, there are parts that are
> strident, and yes, they are dated. Those parts were pretty much done
> in the spirit of Matthias Ettrich's original "LyX Manifesto" at the
> start of the realllly ooooolllllld docs that preceeded my efforts.
You hit both points on the head here. The tone and (carbon) dating of this
part deserve a face lift.
> Second, I want to comment on Word's "ease" of using templates. I've
> spent DAYS carefully massaging a Word template to get it to give me
> even 50% of the consistency of LyX + LaTeX. Then, out of the blue,
> one day, Word blithely redefines a bunch of my document styles. Never
Yeah, I know this one extremely well. I think I've said elsewhere, I support
users who run into this situation, right while they're in mid-hysterics
because the document they have several hundred hours into developing has to
be delivered to a customer in a couple of hours. In fact, just last Friday,
I ended up helping one of our other IT folks in tracking down a way to fix
several _hundred_ documents that go corrupted on one of the shares of our
network. <grrr>
> I think we can take the experience described above, iron out the tone
> of frustration and aggravation, and present it in a
> compare-and-contrast description of what LyX gives you over "document
> templates".
Okay, while making a statement from that kind of experience is useful, the
problem that I see is that we shouldn't be narrowing our range to a single
product. Word sucks, I think we all agree on that. However, there are many
more products on the market to consider. I dislike the ideas of limiting our
comments towards one product, when what we are talking about is a fairly
paradigmatic shift in terms of ideas being employed.
IMO, there was a much stronger argument presented in an article that
appeared in one of the magazines recently (someone posted a link to it on one
of the lists) that pointed out that one company found that removing the
"productivity" software from their systems, and focusing on applications that
smoothed the work flow actually improved the employees overall productivity.
(It moved from this point into a very strong argument for LyX.)
All I'm saying here is that I would like to see the arguments presented in
this section be more applicable towards all WYSIWG word processors, while
making the WYSIWYM methodologies as strong as possible.
> George, you've hit the nail on the head. Coming up with a good
> organizational scheme was one of my original nightmares! Whole
> chapters kept sloshing from the UG to Ref to Custom and back again (at
> that time, there was no "Extended").
:) Hearing you say that tells me a lot about what you were up against.
> If the UG is too large, people don't read it at all: it takes too long
> to find anything, not to mention to load and/or print.
Definitely agree. That's why I think the UG and Tutorial stay (basically)
the way they are, with just some internal editing to be done later.
> IF you have the information spread over too many documents, again, it
> takes too long to find anything.
That, is where I think the structure of the document is _far_ more important,
and what we are getting at looking at here.
> If you don't put something in the UG, there's this silly political
> implication that that feature is somehow "unimportant" or "too
> esoteric".
Well, as you mention later, we may need to take a hard line here. After all,
our job is to move the user from 'newbie' to 'expert' in the smoothest most
possible way. One of the things that I strongly believe needs to be
emphasized is that in presenting (which is what the documentation does) the
software, we have to keept he bottom line on what the user needs / wants.
The developers certainly put a ton of effort into producing the software, and
getting all of the really needed features into the software, however when it
comes time to present the software it really needs to be presented by the
users.
Others may disagree, but this is a fairly simple model followed time and time
again. And, where it isn't followed, there is frequent failure. (And, if
anyone thinks that I am too heavy handed on this, they should look at what
happens at the design level today - frequently the users are actually asked
to design the software...)
> RefG and Custom, yes. Extended, no. Here's why:
>
> History:
>
> Originally, the Reference Guide was going to be the "cutting edge"
> document. I tried to design simple "entry-sections" that devvies
> could fill in and stick somewhere in the RG. I (or a future Editor)
>
> Didn't work. No one even bothered to keep the keybindings up to
> date. :P
Kinda saw that one coming...:) I've worked on documentation before, and I
know what happens here.
> So, Customization and the one or two useful chapters from the RG
> should be merged into one doucment.
>
> The "(Over)Extended LyX Manual" originally began life as "Advanced
> Features". My idea was simple: "Info" told you which doc to start
> with. "Tutorial" was where newbies went. UG was where the more
> clueful user (or LaTeX die-hard) would start. It would document ---
> with examples --- those features that everyone would be using 50-80%
> of the time. Any neat-but-more-specialized features, like fax
> support, would go in the "Advanced Features" doc. So, too, would the
> documentation for user-defined *.layout files. For political reasons,
> however, the name changed to "Extended" (some people got all in a huff
> about the word "Advanced").
>
> Maybe it and the UG should be renamed to "User's Guide, Volume 1" and
> "User's Guide, Volume 2".
Whew. I was (and still am) acutally leaning the opposite way. The
"Reference Guide" really is the technical nitty-gritty that most users won't
want to see, at least not until they are at a sufficiently advanced level.
The Extended document is exactly as you describe it: Over-Extended. Just
lots of stuff in there that I would have expected to be more in the Reference
Guide, dragged me down into details that I just didn't see the relevance or
usefulness to an advanced, but not expert user of LyX.
Hmm, food for thought as I work on an outline...
> > Yeah, most of the into in the UG could probably be moved to Intro.
>
> Don't bother moving it. Let's drop the propaganda (a holdover from
> the Matthias Ettrich days, anyhow ;) ) and just have a paragraph or
> two "tooting our own horn", just to demonstrate to the M$ Word crowd
> what they gain from LyX. And, we can be magnanamous and state what
> you lose.
That's worth considering. Something more like that is probably better in the
UG than in the Intro as we really want the user's first experience to focus
on getting into the product, and not on the hype. :) Hopefully, once they've
seen a bit of LyX's power, the 'hype' will actually convince them, and make
them want to progress onwards.
> I'm not on the lyx-users list anymore (too much traffic to keep up
> with), so I can't be too sure of what I'm about to say. At the time I
> was LyXDoc-Grand-Poobah, almost all of the FAQ that came through were
> questions of the form "How Do I...?"
I'm going to reserve most of my comments on this section. I think Mike and I
started mis-communicating when I brought up this point. And, without having
reviewed the FAQ's it's probably not a good idea to get into this too much.
But I will add one comment:
> Didn't happen. No one bothered to fill in "HowDoI.lyx" beyond the 2
> or 3 entries I put in there to start with. Alas, even if someone had,
> I doubt anyone would have made sure it dovetailed with the other docs.
This fits what I was thinking, and in fact, I mentioned that one of the
things I do as I read through the User's list is to keep a separate folder of
many of the Q/A messages that I find interesting or useful.
I should explain that in my previous experience with a software company, I
wrote a lot of "white papers" and FAQ type documents. And, the method I just
mentioned was the way I went about putting them together. <heh> I was good
enough at it that my boss generally came to me to find out when we had
mysterious bug reports that he couldn't find the original messages on, or if
there were old messages that he needed to refer to that he couldn't find. I
generally had the meat of what he wanted in an easy to find place. :) (And I
actually still have all those messages backed up on a CD someplace in case he
needs them! :)
> Last Topic: The "daunting" LyXDoc Style Sheet.
[...]
> This, gentlemen, is why the Style Sheet is so strict and emphatic. If
> you fail to specify *exactly* what the rules are, if you leave any
> wiggle-room, your volunteers will send you whatever they feel like,
> leaving you to either fix it or let the docs descend once more into
> chaos. So, beware of wasted effort trodding the path that I already
> walked.
I don't think either Mike or myself have any thoughts of making changes
in this area. In fact, having strong style-sheets and templates was
_exactly_ the reason that I was drawn to LyX in the first place, and I see
that as a critically important element of all of documents - especially LyX's
own documentation! (After all, it is a matter of practice what you preach!!)
--
George J. De Bruin
Check Out 0l0rin's New Age compositions at http://mp3.com/0l0rin
0l0rin's latest recording "Collection" is available now!
