On Sat, Jan 08, 2005 at 08:35:11PM +0100, Uwe Stöhr wrote: > > Reasons: > First I just wanted to update the documentation for LyX QT 1.3.x and > make a bit more platform independent. But while working on the > UserGuide, I realized that it is really out of date. The last complete > rework was done in 2000 for the LyX 1.0.x series. In the meantime many > updates and new sections were added. But the documentation still misses > many informations and doesn't follow a structured concept.
Doesn't follow a strucutred concept, eh? Maybe you should read the mailling list archives before insulting me. > E.g. not all menus are described and there is no explanation for the > icon buttons under the menu bar. Ignoring the toolbar was a strategic move. Since tooltips will tell you what they do, it becomes obvious which menu items they're shortcuts for. If you don't know the corresponding menu item, then you clearly don't need it yet. Why are you wasting time messing around with arcane features? Get back to work on that document you're writing! ;) Not all of the menus are described because one doesn't need to know what they all are. One only needs to know where to find the features that one'll use most frequently while writing your average document. Again, a stragetic move, and one to give the docs a clearly-defined structure. I do agree, however, that 4 years of drift have rendered the documented menu locations of many features wrong. That certainly needs to be corrected. > Plans: > I would rework the Tutorial and the UserGuide. > The UserGuide would contain a section with an overview of all menus > and icon buttons. There is a chapter in the Reference manual for this. That is the logical place for it, as I said in the original description of the documents' strucutre. > But I want to delete platform specifig stuff like "Configuring the X > keyboard" etc. "Configuring the X keyboard" could probably go. Life on Linux & X has improved rather significantly in the 7 years since we added that. > and ironic comments. (These comments are often funny but > shouldn't be part of a manual.) ...because manuals should be as dry as dust, and so boring that nobody looks at them? > At last I want to merge the Customization and Extended manual. Some > of its stuff will be part of the UserGuide. Bad Idea. I suggest you look through the mailing list archives for my earlier emails where I describe the structure of the docs. These two files were split off for a reason. > I started once with a new layout for the UserGuide in koma-script book > format. <sarcasm> ...because *everyone* is German and therefore uses a German-centric LaTeX class like koma-script. </sarcasm> Uwe, if you are going to do this, and you want something that ALL of us can use, you need to start looking at the docs through the eyes of all of the users, not just from your own point of view. This is why I'm so critical. (While editor, I was equally critical of contributors for exactly the same reasons when they veered off course into their own narrow perspective.) Right now, I have doubts. I read a lot of high-flying ideas from you, with very little grounding in practicality. Let me give you an example of what I mean by "practicality": The "Customize the X keyboard for non-US-English". We added that because the lists were getting about 2-3 "Heeeelp Meeeee" messages a month asking for this information. There was a practical reason for adding it to the docs, so in it went. There were practical reasons for the division of the docs. There were practical reasons for the names of the docs. I didn't personally agree with some of the names, but went with those changes, anyway, because my suggestions didn't convey the proper connotations to the wider audience of LyX users. As much as we'd all love to have someone, anyone, updating the docs, I have to play Lars here for a sec and ask: are you overdesigining? Do we really need this-or-that feature you want to add? And, in the case of the docs, can you put yourself and your own agenda (printable book) aside and make decisions grounded in practical, broad-user-community-consensus-based reasons? -- John Weiss
