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