On Tuesday 22 May 2001 12:03, [EMAIL PROTECTED] wrote:
WARNING!!! WARNING!!! WARNING!!! WARNING!!! WARNING!!! WARNING!!!
What you are about to read is one *extremely* long message. (Over 200
lines!) I had a 'gestalt' after reading the other comments, and decided that
it was a concept that should be tossed out there to see what reaction it got.
However, as I put it together, it has turned out to be fairly detailed and
quite complicated (although the results of it should appear simple and
natural to the user).
Please read this message carefully, but keep in mind (a) it is just an idea
that I am tossing out there, (b) I'm mainly looking to see what kind of
reactions I get to it, and (c) any additional suggestions, tweaks, etc. are
appreciated.
If you have flames for this idea, you may direct them to me, however that
will be treated the same as directing them to nul. :)
END WARNING END WARNING END WARNING END WARNING END
> This is true, but I actually think you got the balance of the UG content
> right - other than updating and perhaps smoothing the tone a bit, I really
> don't want to change it. I imagine the UG as the thing to read if you want
I agree, however I do have a thought (as ever) that might be of interest, and
(maybe) add some value / benefit to the documentation above and beyond what
the current set accomplishes. Read my comments towards the end of this
message.
> Well, there are my two documents :-) I imagined one remaining essentially
> Extended, with perhaps a few things moved in or out; the other would be
> Custom with the most relevant parts of Ref moved in (e.g. keybindings).
Again, in essence I agree, with the caveat that I have some thoughts that I
want to "bounce" off you guys to see what you think. :)
> > > 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.
>
> Okay, I like this idea.
I've gotta admit, I'm not convinced on this point. The fact is that the
Intro feels very much out of place. In fact, when I looked at it the first
time, I thought it was very much a throw-away document that I would never
look at again, even though there is some useful information in it.
Why did I have such a reaction to this document? Well, it was six pages of
information that I only got two things from: (a) a brief description of the
documentation formatting / navigation, and (b) a description of the other
documents (which told me the really obvious thing: I really was looking for
the tutorial). Then there were things that I wasn't interested in at this
point (The Documentation Project? I don't even know _how_ to write a
document with LyX yet! Why am I even going to consider this?)
Of course, looking at it now, I see there are things in there that are
necessary: the format of the documents, and the list of the documents (yeah,
okay, as a general user I might skip this, but later it will probably be
useful, and long forgotten...)
Another problem is that it's kind of an odd-duckling document: no chapters,
only sections. Just makes it feel like it's a hacked-up document of
bits-n-pieces that probably should go together, but really should be in a
larger context.
> Ahh, I see George just chimed in, and that we agree fairly well. Perhaps
> in thinking about the outline of Extended (well, really all the docs), we
> should keep in mind the LyX/LaTeX "split" between UG and Extended, and
> base the overall structure on that. Perhaps this should be stated
> explicitly in the Intro as well.
Okay, here was the big thought that resonated in my head yesterday (the one
that I mentioned earlier in this message) that I wanted to bounce off you
guys:
First, I stated yesterday in response to John's message that I still think
that re-organizing the Extended, Customizing, and Reference documents is a
good idea. And, in fact, the above split that Mike stated actually makes
more sense, but I think needs to be looked at more carefully.
Second, I stated above that the Intro still feels like an "odd-duckling"
document to me. It's a bunch of sections that mostly go together, but need a
larger context.
Third, in looking at this again this morning, I see an issue of
'documentation spread', which bears similarity to feature spread in software,
and frequently turns into feature bloat. :) The problem is that the main
body of the documentation is in six seperate documents, and that tends to
lose the focus for the user. Being relatively fresh to all of this, I am
speaking somewhat from experience here. By the time I sat down and was
really working my way through the User's Guide, I felt like I was getting
relatively profficient with LyX, except for those exceptions that I hadn't
been able to find in the documentation yet.
So, there I was, trying to get the information that I needed, reading the
User Guide, and fumbling around in four additional manuals. Most of the time
I was able to find the things I was looking for, but there was also quite a
few things that I didn't find, and there was some frustration from it.
I think the reason that I hit this situation was that I was working my way
through the standard user process in trying to learn and understand the LyX
as I would any other product. And, this is a process that I think most users
follow as well. (IE, they read the documentation, but frequently have to
read things out of order to get the level of information that they want.)
So, what I've been thinking now is how can the documentation be better
organized so that it can be read in a linear manner, but also be read in a
non-linear way? I think the answer comes down to the fact that there are
basically four stages for users, but not all users go through all four stages
completely. Here are the four stages:
Newbie: the user that is just getting familiar with LyX. Just needing a
fundamental understanding of how to create a document. Not needing heavy
detail.
General User: User's that use most of the features of the product, but don't
necessarily use all of them heavily. They need a good understanding of all
of the major features, and sometimes need additional / detailed information
on specific features.
Advanced / Power Users: these people use LyX heavily, and do a lot of
detailed work in it. Frequently need to adjust the behavior of LyX in some
respects. And, they also do some customizations (things like changing key
and menu bindings, adding external utilities like Pybliographic, etc.)
Super Users: these people not only use all of the features extensively, they
have needs that go well beyond minimal customizations, and working with the
templates and classes provided. (These are people that will do things like
adding heavy ERT to modify a classes behavior, modify the preamble heavily,
make their own templates, possibly even add their own classes.)
There is also another level of 'user', but I think this goes beyond just
being a user. And that is, the kind of person that does the implentation and
administration of LyX.
Okay, now, given the four major types I listed above, I think the
documentation should be a reflection of those users. Newbies need the Intro
and Tutorial documentation. General Users need the User Guide. Advanced /
Power users need a combination of the Extended and Customization Guides.
Super Users need a combination of the Extended and Customization Guides and
some of the Reference material. The remainder of the documentation should be
in a Reference manual for maintainers / administrators.
Having broken down (roughly) how to organize the documents into a structure
to represent the user heirarchy I've outlined, there is a bit more to say
about how to organize them. I mentioned that not all users progress to the
same stages at once, and sometimes that may never happen. While I may need
to know something extensive about working with paragraph environments, or
tables, I may never need to know how to implement a whole new environment.
What can help in this situation is to try to make the documents paralell each
other in structure as much as possible. Let me explain this by way of
example: say I'm reading the tutorial and I am reading something on list
environments in section 3.5.2, and I find that I need some addtional
information on that type of environment. I deally, I would be able to open
the User's Guide, go to section 3.5, and quickly find additional information
on the environment that I was reading about in the Tutorial. If that still
didn't answer my questions, I should be able to turn to the Advanced
documentation, look at section 3.5 and find more information that relates to
the topic in the Tutorial and User Guide.
Obviously, the paralleling of the structures between manuals doesn't carry
all the way through the documentation. Each document brings in new and
additional information that doesn't have parallel's in it's predecessor.
But, that can be handled by breaking the documents into parts. By grouping
the chapters and sections that do have parallel's in one part of each
document, and cross referencing to the sections that don't parallel, I think
we can provide the user both linear and non-linear paths for reading the
documentation.
----
Finally! Got all of that on screen! (It's taken me two days to write all of
this, it's more complicated to try to write it all down, than it is to think
of it! <g>) I am reasonably convinced that the ideas that I've outlined
above can be accomplished with the current documentation, just mostly through
re-organizing / re-structuring it. And, while I know there could be some
resistance or political issues from others, I think that understanding this
kind of structure might actually smooth some ruffled feathers. (Hey, who
amongst the development team doesn't appreciate well structured, well
organized, logical presentation? :)
> Well that's my idea of the day. George - might this help address some of
> the "linearness" in Extended that you see? Something like
>
> Common LaTeX extensions (minipages, etc. things commonly found in teTeX)
> Alternate styles (aapaper, AASTeX, RevTeX, etc.)
> Operating System extensions (fax, lyx2html, etc.)
I think this is basically the kind of break that gets defined between the
Power Users and Super Users. IE, explaining each of the classes goes into
the Power Users, while how to modify the behaviors of them go into the Super
User's documentation. Does this make sense?
Okay, I know this is an extremely long message, and will probably take a bit
to digest. I actually think it should be read twice, maybe even three times
before commenting. <g> As I said above, it took me a couple of days to write
it all down. The idea was almost a gestalt to me when it hit me, but it took
far longer to write it down, and bears a lot of thought.
--
George J. De Bruin
Check Out 0l0rin's New Age compositions at http://mp3.com/0l0rin
0l0rin's latest recording "Collection" is available now!
