Hello George,
I've forwarded your message to the lyx-docs mailing list. If you haven't
subscribed to it yet, you should. It's very low volume - completely in
the noise compared to lyx-devel :-)
On Fri, 4 May 2001, George De Bruin wrote:
> However, I was thinking while we aren't to the point of working on the update
> of the documentation for 1.2 yet, this might be a good time to discuss, or
> consider some ideas for restructuring or reorganizing the documentation.
> That way we can look at it with the finite set that we have to work with,
> then start with that for the new documentation.
Yes, this is wise. I'd like to keep the User Guide more or less as it is.
Updates, or addressing the intro as you suggest below, are needed, but
structurally, I think it's pretty good. Not to mention I don't want to
obliterate the hard work John Weiss already put into this. But it is in
danger of becoming dated if we aren't careful with it.
> For example, one of the things that I was thinking is that the Extended
> Features documentation is rather linear, which can make it difficult for new
> users to find things. What if, instead, the document were organized into
> parts that were more reflective of the structures used in LyX. An
> (incomplete, and completely off the top of my head) exmaple of such
> organization might be something like:
>
> - Document Part
> - Document Class Section
> - LyX Document Options Section
> [ ... ]
>
> We could play with such an organization now, see if we can come up with
> something clean (I would say no more than three levels deep), and reasonably
> well balanced.
Might work. I've often wondered if we could recombine Extended,
Customization, and (the almost thoroughly useless) Reference Guide into
two, more compelling, documents. Care to take a crack at an outline (using
the existing Section/Subsection headings)?
> I was also thinking we might want to review the other documents in a similar
> manner. For example, the opening section of the User's Guide has all the ear
> marks of being major propaganda, which I have nothing against, but I wonder
> if it wouldn't be better to get users on to the main subjects, instead of
> spending a page and a half on this. (After all, most that have read past the
> Introduction / Tutorial are already sold on LyX.) Maybe two short
> paragraphs, and refer to a longer document in an appendix or another document.
Yeah, most of the into in the UG could probably be moved to Intro.
> Also, maybe look at adding an FAQ or Q&A type document. There are lots of
> similar questions asked on the LyX User's mailing list all the time. Herb
> Voss has invested (I suspect) a great deal of time in developing his web
> pages, but really, the user shouldn't have to go digging that far for many of
> the answers he has up there...they should be in the documentation. I'm not
> suggesting trying to compete with Herb's web site, however a clear review of
> the User's list for frequent questions and answers, would be in order, IMO.
> (I have a 'LyX Save' folder here that I use to store stuff from the User's
> list that I think might be important to me... That might be a place to
> start. There are already 70 messages in that folder.)
Ahem, there is a much ignored FAQ in the documentation. It even points to
Herb's site. Given that Herb's site is so good, but focussed a bit more on
tips and tricks, I want the FAQ to cover the true FAQs, then point to
Herb's site for everything else. However, unless the FAQ ends up easily
accessible on the LyX Web site, I fear it will never be of much use.
Despite repeated requests to get it there, it has never been included ...
You've presented some good ideas. Anyone else care to weigh in? I suspect
John W will have some strong thoughts on the matter - I'm not sure if he
reads this list or not.
Mike
--
Mike Ressler
[EMAIL PROTECTED]
OK, I'm lame: I don't have my own website ...
