[kde-doc-english] Doc team website

[Carlos Leonhard Woelz]

On Wed, 27 Jul 2005 14:15:37 +0200, "Lauri Watts" <lauri at kde.org> said:
> Now that http://docs.kde.org has been fixed up and is a rousing success,
> our thoughts turned to other sites, namely the documentation team pages 
> themselves.
Yes, I was thinking about this myself yesterday.
 
<snip content focus rationale>

> So, here are my notes, from a very late night brainstorm session:
> 
> Target Audiences we should consider
> ===================================
> 1: Potential Contributors who want to 
> 2: Application developers who want to add/improve docs for their app
> 3: Existing team members, looking for reference information, or for
> further jobs to do
2 and 3 are easier to deal with. A central place for the documentation
guides, clearly maked, should do the job.

The real challenge is clearly 1. We can take a lot of the info from the
doc-primer.

> 1 can be broken down to smaller groups, that overlap some, but may be
> looking for different information:

> 1a: People who have a good grasp of English and write well, but have
> never written documentation before
> 1b: People who have some experience with docbook
> 1c: People who have some experience with technical writing

1d: (me) People who have good or reasonable knowledge of english, are
not programmers, but are very motivated to help KDE.

Writing documentation forces you to review and test all the app
functionality, giving you leverage to write good bug reports, write
context help, write usability reports, etc... I believe that writing
documentation is the best way to start helping KDE, if you are not a
programmer, even if your english is not perfect. Writing good, non
obvious docs is hard work, but it really pays off.

> for instance, people in group 1a might need information about learning 
> docbook, and how writing technical documentation differs from writing a 
> simple web page howto. People in 1c might be ready to jump straight in.  
> Providing the required information to 1a should not get in the way of 1c 
> diving right into work.

Somehow, I don't think that 1c is the problem. Just write somethin like:
"If you already have experience with technical documentation, you may
skip this introdutory section/page/whatever and jump to foo"

1b is a little more challenging: the guy probably *thinks* he can write
good docs (hehe, I include myself here) and probably can. But how to
help these guys to really write good, attractive, usable, task oriented
docs? Part of the KDE docs show that the writer was performing a boring
but necessary task, not trying to really communicate something to the
user.

Please note that I am not dreaming here: I know we have a "man power
problem". It is not hard to improve the situation when the docs for an
app do not exist, are wrong or outdated, so the bar to contribute is
low. What I am saying is that it is important to reach the existing
docbook writers and and help them write usable docs. I would welcome
such guidelines / feedback.

> Front Page
> ==========
> * The *first* thing on the docs page should be something like "Want to
> join the docs team? Here's a simple <n>-step guide". 
Agreed.. Just a few paragraphs in the front page, just like in the
quality team page.

> * Ideally <n> is very small, and includes "please contact the doc team"
> very early in the list.  
Yes, that is what I did in the quality pages too.

> * We also noted that we might want to emphasise "Do you want to
> contribute to KDE" over "join the docs team".  Or not, this is something to discuss.  
I think that the motivation of lot of people from 1a/1d is related to
this, so I really welcome that.

> * General decluttering.  Shorter texts, turn the front page into more of
> a roadmap where everything is, rather than trying to jam things onto it.
> * Write a very brief mission statement, to emphasise we are not scary 
> monsters, we are here to _help_ you get started.
Sure.

The only question: how can I start helping out!
 
> Info for app authors who want to document their app
> ===================================================
> * to some extent, we can just say "read ch x, y and z of the Doc Primer,
> and maybe some stuff on developer.k.o" for them
> * Additional info (that may need to go in the doc primer or on pages): 
> where to get the template to start from scratch, what's the minimum
> requirements, what to put (and not put) in their Makefile.am, how to
> package them so they install correctly (one of the svn2tar scrtips was
> quite broken)
> * What application maintainers should be telling people who volunteer to
> write help for their application (first on the list must be please tell
> the docs team.)
Agreed, but we should focus on the writing guidelines as well. The
programmers may need some guidance, after all it is a different skill.

> General Points
> ==============
> 
> Definitely we need to be carefully wording things to try to diffuse this 
> impression people have that docs is something you might do while learning 
> code, and isn't worthy of best effort in and of itself.
> 
> We definitely need a FAQ of some kind to explain why there are all these
> funky arcane rules about doc'ing (indentation, entities, credits, etc.)
> 
> Someone noted that they were quite confused by the documentation being
> split around three places (docs.kde.org, www.kde.org/documentation and 
> i18n.kde.org).  We've already cleaned out most of what's in www.k.o, and 
> almost all url's should now be pointing to docs.kde.org.  If you're aware
> of any that don't, this is also a good opportunity to clean those up.
> 
> As far as location, we would like to put the pages themselves at 
> http://docs.kde.org/team/ (and possibly mirror them at i18n.k.o, since
> there are a lot of links going to there already.)  We'd also like to get
> these pages into the normal SVN tree, to make it easier to work on them. 
> Graphics and Layout should be taken care of by the normal media framework of the
> KDE sites. 
Agreed.

Cheers,

Carlos Woelz