On Tuesday 23 March 2004 20.26, Marc Heyvaert wrote: > Hello all, > I thought it would be better if I did this outside the > KOffice project for a number of reasons. Lauri thinks > that it would be best if keep my efforts within the > project and work on the current version in CVS. (This > seems to have important advantages, that I'm not going > to repeat here :) ).
I should note, in our conversations, and those with some other new writers, I've come up with a few things that could and should be added to the docs site, and perhaps should be made clear to all new KDE contributors in general. More on that in a separate mail. > I have had another look at the existing documentation > for KSpread and some other KOffice application and the > majority of the existing handbooks are very concise, > very direct, almost in telegram style. I think the > same applies to a lot of other KDE Handbooks too. Is > this some sort of policy? More or less, yes, especially for reference style manuals - clear and concise is just what you need when you're looking up how to do something specific, or are trying to solve a problem. It's also a whole lot easier to translate than anything more casual. As always, things are more flexible than they first appear, tutorial section, for instance, can be rather less formal. There's some things worth reading here: http://i18n.kde.org/doc/styleguide/ (and indeed, the entire http://i18n.kde.org/doc/ section) > Are there limits in total > size and size per chapter that I should respect? > Should I aim for a long version outside CVS and a > synopsis in CVS? I'd like to have your views on this. There's no limit, other than how much you want to write :) It is practical to keep *file* sizes limited, they are easier to manage both for editing and for translation if you chunk them up into bits, but as many files as you want is fine (take a look at kword's manual in CVS :). We've never really settled on a maximum size, but when knode's manual was a single file and was about 60Kb, we got some requests from i18n to break it down. You can break to another file at virtually any element, so you might have some where a whole chapter is in a file, and others where it's a sect1 per file. > As for my current train of thought...this is how I > would like to proceed : > > The manual that I see before me has 3 parts : > I. A general, traditional handbook approach covering > with a chapter for each major topic. Topics should > include : <snipped excellent looking outline, purely for brevity> To comment on something further down the thread, yes, it's completely possible to have multiple entries in the Help menu - in fact, the koffice applications already do, if you have the thesaurus tools installed, they have their own help menu entry, in addition to the standard ones. > Printing a spreadsheet; > Creating a PDF document; > Fitting your spreadsheet onto one page; > Adding headers and footers to your document; > etc. > > This is the 'flexible' part of the handbook. We could > start with a couple of items and continue from there. > So in view of what I intend to do, I would like to > have your opinion regarding scope, length, etc. We've actually discussed this kind of thing before, although I can't find it in the archives. From what I remember though, we decided these kind of things work well when kept very focused on a single task, and about the length they can be printed on a single page as a 'cheat sheet' The mistake often made when writing this kind of focussed how-to, is trying to cope with corner cases or troubleshoot problems right then and there, when these things are irrelevant to 99% of the target audience (who aren't having a problem, they just want to learn how to do a new thing.) It's much more succesful (read, there is better and more feedback from users) when the tutorial assumes a working installation and nothing goes wrong, and points to the rest of the manual for handling those situations. Now I'm thinking my explanation there isn't very clear, so to illustrate: Basically - This works: =================== To do foo: 1: Do bar, 2: open baz 3: Type your name 4: do magic stuff 5: your foo is now ready If you have problems with baz not opening, please read <xref something else> then continue with step 3. If you don't know your name, please ask your mother, then return to step 4. ==================== This doesn't: ==================== To do foo: 1: Do bar 2: Open baz. If baz doesn't open (three paragraphs sorting out the 1% of people who don't have an opening baz) 3: Type your name (a couple of paragraphs over-explaining exactly what we mean by 'name') 4: do magic stuff 5: your foo is now ready ===================== Even though the content is more or less the same. Direction, rather than distraction. Of course, as I said, these kind of things can be less formal than the normal style, and writing three paragraphs on one step is fine, if that is what the step requires. > I would consider this a testcase, a possible model for > reworking the rest of the KOffice documentation. I > believe that having good extensive manuals is > absolutely essential for the promotion of KOffice. > Especially because there is a great potential in > education where young people, who are not yet > prejudiced can still choose for the spreadsheet (same > for other applications) that serve them best. The > documentation can play a major part in this. Preaching to the choir here! I think we're definitely all behind you on this and will endeavour to give as much support as we can manage. > Migration path. > 1. I make an outline of the whole handbook and publish > it here for review. > 2. Next we should break up the existing handbook > written by Pam and plug the different parts into the > right slots in the new structure. > 3. Then I can start filling in the holes. I would put > up every bit here first for review (and to correct the > inevitable mistakes a Belgian will make against S's > language :) ) This looks like a great plan. I also think you underestimate yourself, and it won't take long before the review process will boil down to 'looks great, commit that as is', although I'll admit we are master nitpickers around here (that's a feature, though, not a bug!) > Perhaps we should Tag the current version (I believe > there are still some patches from Rafael Langerhorst > with Lauri), so that we can always come back to this > version if we are caught up in a new release before I > get somewhere... I have (I believe) all Rafael's patches committed. I'm not sure a tag is necessary, since we can as easily revert to a date as anything else, but I've no objections either, so tag away. Regards, -- Lauri Watts KDE Documentation: http://i18n.kde.org/doc/ KDE on FreeBSD: http://freebsd.kde.org/ -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 187 bytes Desc: signature Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20040324/236d7d75/attachment.sig
