[kde-doc-english] Doc team website

[Lauri Watts]

Hi all, 

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.

We had an informal brainstorm session on IRC last night, and I've noted below 
a few of the points that were raised, and things we need to think about.  At 
this point, we are not discussing graphics, page layout, or colours, part of 
the change is to move to the standard php framework used by all the KDE 
sites.  What we're interested in is rearranging (or rewriting) the content to 
make it more accessible to our different targets, and easier to find what you 
want to know.

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

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

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.


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".  
* Ideally <n> is very small, and includes "please contact the doc team" very 
early in the list.  
* 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.  
* 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.

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

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. 

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-doc-english/attachments/20050727/b33db287/attachment.sig