[kde-doc-english] KOffice/KSpread documentation

[Lauri Watts]

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