[kde-guidelines] How to Write

[Lauri Watts]

On Sunday 26 September 2004 03.26, Frans Englich wrote:
> Thursday 23 September 2004 10:02, Ellen Reitmayr wrote:
> > Hallo,
> >
> > Aaron asked for the current status of the project, and Frans asked for
> > some information on how to write - so here we go!
> >
> > During the last two weeks, Lauri, Jan, Thomas and I were making further
> > specifications for the format of the new HIG. Lauri modified the docbook
> > format so it would meet our ideas and what we discussed at aKademy,
> > #kde-usabiliy, and #openusability.
>
> I would like to help and bring input to any technical details, so don't
> hesitate to post DTDs etc. (but I guess I should have been at aKademy, for
> example)

We'll probably be using the standard version as used by all KDE documentation 
(Currently a slightly customized version of DocBook 4.2.1).   Unless someone 
comes up with a really really good reason to not do so, it provides a lot of 
benefits.  

> > I wrote an example chapter to see if
> > it fits. Currently, Lauri is transforming the texts into docbook format.
> >
> > The chapter is intended as a discussion base - both with respect to the
> > format and the structure of contents. I do not want to describe it in
> > detail now, as it is easier when you will see the example. Just so far:
> > We tried to find a way to allow users to separate guidelines from
> > examples and rationales if they need a quick implementation hint only,
> > but at the same time providing the full information for those who are
> > interested.
>
> Sounds like what Lauri posted some time ago(09/01):
> http://people.fruitsalad.org/lauri/igs/test1-chapter.html
>
> Looks nice. Looking forward.

I have a good deal of Chapter 11 (with real content) already marked up, as 
well as a framework book around it (including a bibliography, glossary and 
index) more or less ready to start pouring more content into.  I took the 
weekend off to hang out with family, and there are a couple of things still 
to discuss with Ellen, but I should have something ready for her review by 
tomorrow, and I expect you all will be seeing it soon.

> > We found that quickly finding relevant information is one of
> > the major disadvantages in other HIGs (as they provide all of the
> > available information permanently on one page).

> Speaking from my experience, it often happens in major projects, especially
> writing(13th rewrite anyone? :), that ideas and plans changes, which is
> quite naturally and understandable. It almost never gets right from the
> start, but is a gradual process towards that perfectness. As the popular
> phrases says, "release early, release often" -- and with tempo. Of course,
> markup specifications is a must(why is it changed..hm..), but things like
> organization can be changed as we go, and easily so.

There is a difficulty in doing this when writing something that is a set of 
specifications or guidelines for others to follow.  It means they may well 
read an early version, and follow it quite nicely, but not keep up with 
changes to the document itself, and so you'll reach a situation where, when 
someone says "I followed the guidelines" you have to ask "which version, and 
what date was that released on?"

While this will of course happen anyway, it would be of great benefit if the 
versoin actually published to the final audience is as correct as possible.  
That's one of the reasons to institute a pre-publication review process. 

The flip side of that is, once it is published to the final audience, it's 
much harder to push through content changes.  That's another reason to do as 
much review as possible before final publication.  Once it's out there, we 
are, to an extent, stuck with it.

> I literally hate the chaos, incorrectness, and incompleteness, evolution
> and rapid development brings(such as open source), but it works pretty well
> in the end.

For code, yes.  For artwork even.  For writing, perhaps not so much.

> > We have not yet thought about language specifications and wording - I
> > think that should be done by a native speaker... Of course it should be
> > sane and consistent, maybe we should set up a table of terms that are to
> > be used for certain things (e.g. is a menu item a item or an action?).

This kind of thing I can have some input on:

As far as KDE docs have been concerned until now: A menu item is an item in a 
menu that initiates an action.  The action could also be initiated by 
pressing a toolbar icon, a keybinding, or perhaps automatically when a 
certain operating condition is met.    That is, the action is "opening a 
file", the menu item "File -> Open" happens to initiate that action, and 
pressing the toolbar icon would also initiate it.

This kind of thing has impact both ways for the KDE documentation - it's not a 
bad idea to keep terminology consistent as much as we can, 

Regards,
-- 
Lauri Watts
KDE Documentation: http://docs.kde.org
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: not available
Url : http://mail.kde.org/pipermail/kde-guidelines/attachments/20040926/515a9994/attachment.pgp