Uwe Stöhr wrote: > Georg Baum schrieb: > >>> When a new feature is implemented to be released in the next LyX version >>> the developer(s) who wrote the feature create a separate LyX-document >>> describing the feature. Then somebody who wasn't involved in the >>> development of the feature checks if he's able to use the feature as >>> described. This would help us to implement features user friendly >>> because the revisers of the document will lead to feedback about the >>> implementation, the usability and the stability of the feature before >>> the feature is released. If the feature is stable its describing >>> document is implemented into the userguide. >> >> This is too complicated IMO. I would already be very pleased if >> developers who implement a new feature/rearrange menu entries would >> simply add a section to the appropriate manual/reflect the changed menus. > > For me it is easier to have separate small document describing the new > feature. I'll revise it and then inlude it to the official docs. This > has the advantage that a professional bug finder ;-) will give feedback.
I can understand that. My point is this: If I have to choose between suboptimal written documentation without having a professional bugfinder looking at it, or no documentation at all I prefer the suboptimal version. >> I fear that if these things have to be implemented in a separate document >> documentation updates will happen even less than it currently does. > > You misunderstood me, the separate documents are only for the > development, they won't be published but included to the official docs. I don't think that I misunderstood you. I do want development happen in the userguide (and the other existing documents of course). IMO, with the procedure - implement new feature - commit the code changes - create new doc describing it - put new doc in svn and commit it - sometimes later, move contents from new doc to Userguide, remove the new doc from svn and commit all that documentation updates are much less likely to happen than with - implement new feature - describe it in the user guide - commit the code + documentation changes And all the documentation needs to be in svn IMO. If it is not it will be forgotten and not seen by many people. But even if you skip the svn part for the new doc and put it on the wiki instead it would still be considerable more work. Given the fact that many new features are currently not documented at all, without the requirement of separate docs, I very much doubt that you would get better documenetation if you require separate docs. >> Uwe, I think that you should work on the official documentation from the >> beginning, and put it frequently in svn. Otherwise I fear that we'll get >> a situation similar to your windows installer where there was a lot of >> duplicated effort. > > But that's what I want to do. To say it graphically: > > separate document for new feature > | | > ^ ^ > special document ---> Userguide > basics > > So it ends up in the Userguide. > > And by the way, I plan that the version UserguideNV I'm working on will > become the official version. It is very similar to the actual userguide > but includes more informations about the UI. I don't have time to look at that yet, but IMO you really should do this work in svn and not somewhere outside the official LyX project. I can assure you that if you come when it is finished and want to replace the current Userguide there will be objections, and the result will either be additional work for you to get it accepted, or your version will never show up in the official sources. If you do your work in svn, on the current version with frequent commits, then it will be less work in the end, because no big change will come at once, and if there are objections to one step you will get to know them immediately, and they can be resolved quickly. Georg
