[kde-guidelines] How to Write

[Ellen Reitmayr]

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 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. 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).

There are still some problems with the format - and we want to discuss
them based on the example chapter. The chapter will cover the following
points:

- Structure of the document (Chapters, subchapters, toc)
- Organisation of contents (Guidelines, Rationale, Examples,
Implementation hints)
- Related Issues (other chapters in HIG, Accessibility, CIG, Artists)
- References to external documents (DIN Norms, Articles, Books etc.)
- Citations/References (Gnome HIG, OSX HIG, DIN Norms etc.)

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?).

There are also some problems concerning the contents - e.g. should we
refer to Qt 3.x, 4.x, or both? but more about that when the example
chapter is online...


Another aspect Frans menioned:
> I looked after DIN/EN/ISO 9241 as Siegfried mentioned, but I only found German 
> texts(doesn't help me :|).

The DIN norms are not public and they are VERY expensive to buy - we
only dispose of the German version. Anyone out there who has access to
the English version??

Greetings,
/ellen



-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://mail.kde.org/pipermail/kde-guidelines/attachments/20040923/bcb5dc39/attachment.pgp