[kde-guidelines] How to Write

[Frans Englich]

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)

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

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

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.

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.

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

Perhaps there's alternative solutions. How hopelessly unreadable is it if you 
run it through a translation service? How long is it, perhaps someone could 
translate it? We have excellent translation teams. Is it an electronic 
version? Do we really need it? I don't know in what way it relates to the 
HIG, and how much insight it requires in order to write content.

But most importantly; what is the EULA for it, and other juridical aspects? Is 
your license per user, company, or something else? (depending on answer, we 
have a range of possible solutions) 

How much does it cost? Perhaps we can get a sponsor or KDE E.V to buy a copy. 
Searching for 9241 at:
http://www.beuth.de/index_en.php

gives results in the range of 100 euro, but what that includes, and what it 
means, is unclear to me.


ISO/RS/DIN -- we all like them.


Cheers,

		Frans