The K-Meleon Documentation Project


What?

The K-Meleon documentation project is an effort to write a user's guide and reference manual for K-Meleon.

It is still far from complete, but Please start to use the manual already. Point users to it when they ask questions at the web forum that are clearly answered in the manual (or the FAQ for that matter!). Without making people more aware of the text it will not be used much and no one will report things that are missing or incorrect..

Why?

There are already several good documents at the kmeleon homepage. They have helped a lot of people already and continue to do so. Still.. They are all hand-holding tutorials, answering specific questions. If you have a problem not demostrated in one of the tutorials you are on your own; Without written help. That's when a manual filled with facts, sorted in a logical way, such that you can find answers to all "How do I ..?" questions yourself comes in handy.

It would be great if this manual can be bundled with the browser one day; either as html or windows help files.

Who?

Participation is open to anyone willing to help. All contributions, large or small, are very welcome. And very much needed! There is no need to write a full chapter or section; a small subsection is good enough. Or simply extend/rewrite/correct the text of an exisiting part. You can write as much or little as you find time and interest for. Both your co-writers and our end-users are grateful for all help you can offer. It is okay to leave comments and quesitons in the text if you don't have all answers at hand (and remember to help complement the missing parts of "others" texts).

Tip: No programming knowledge is required, which makes it a great way for non-programmers to contribute to the K-Meleon project.

The big challenge in creating a Users Guide is doing the work and writing the content. It's a huge project and we need a lot more people contributing to make it happen. One problem with finding writers is that those who know things good enough to write about it have no need, or wish, for a manual. (In contrast to helping with the actual application where you will benefit from your own contribution much more)

How?

The best way to submit additions/corrections/comments is to send them to the K-Meleon developers' mailing list, kmeleon-dev@lists.sourceforge.net, as a plain-text file; that way, other people can make comments on it if they feel they need to before it gets added.

A good way to get ideas of what to write about is to follow the discussions at the web forums. When you find discussions on preferences or features, take a look in the manual whether their descriptions are understandable (or even existing). Write down a short description and have it added, or complement/correct a hard-to-follow description. Perhaps we should also have a pointer to the preferences from an advanced section or maybe from the configuration chapter. Try write something short there as well to wrap the links up in some text.

If there is anyone willing to make available some snapshots (png) of the browser window, menus, and cofig dialgbox views, that would be appreciated. Place them at a web or ftp server, preferably as a single zip file. With a short text for each picture it would be perfect ;)

If you find something you like to write about, but feel you don't know it well enough just yet; Ask for help. You can ask either at the web forum or the mailing list. The knowledge exists, we only lack good writers that can make things clear to others. Pick a topic you like to learn more about. and.. Have fun! That is the most important.

Audience?

When writing a manual it is important to realize that there are different kinds of users, and they demand different kinds of documentation. It's not likely that we can produce a single manual that fits everyones needs (and a too thick book might scare people off from start reading at all).

Three very different user groups are:

  1. Developers: These are the people who need pure reference documents. They want code, code references and perhaps a few explanations. They don't want step-by-step guides, compact tables for quick references would be enough.

  2. Regular Users: They know their way with computers, but not the inner workings of K-Meleon. These are the people who would benefit most from a Users Guide. These are our everyday users who need a reference when they get stuck or want to try out a feature.

  3. Novice Users: These are the people who need the step-by-step guides like the ones at the web site. For people on the developers list, they might seem dumbed-down but as anyone who has answered questions in the forums, there are a lot of people who need step-by-step guides.

The intended audience for the manual is the regular users, but we should also try to give advanced users the references they search. There will be very little in the manual for the complete computer novices, but we shouldn't forget about them. The need to write new (and to complement old) tutorials still exists.

Contents?

The goal is to fill the manual with static information for the version at hand. We leave much of the step-by-step tutorials, macro examples, building instructions, press announcements, FAQs, and lists of skins and third party plugins at the web page (or as separate documents).

A rough sketch for how the chapters can be organized is shown below, but we should still be open for rearrangements if some chapters or sections grow too large or others stay small once we start fill in the text.

Chapter 1: Introduction

Introduces K-Meleon, the application, the project, the community, the philosophy, and puts it all in perspective.

Chapter 2: Getting started

A nice and friendly text that lets everyone get up and going with K-Meleon. Download, install, run, and uninstall. Aimed for the very new user. Much like the tutorials already written by Andrew.

Chapter 3: K-Meleon Basics

Aimed for new users. Explains all fundamental features and the default menus and toolbars. No matter if most users are not all new to browsers, a manual is not complete if you don't explain the full user interface and the meaning behind each little icon. As a starter we can probably get away with just screenshots and short explanatory texts.

Chapter 4: Configuration

Aimed for the regular users who have already worked through a few of the tutorials and FAQ entries. Explain the secret behind each checkbox. Tell the actual prefs variables in use, write pointers to sections in the reference for further reading. That might prove as a gentle introduction to start reading the reference section.

As a starter we can do as with Chapter 3; screenshots with short explanatory texts. It should be okay to keep it short. Just tell the reader what it is all about and where to read the full story.

Chapter 5: Internationalization

For regular, non-English, users that want to change language or character set in K-Meleon.

Chapter 6: Advanced Usage

This chapter is for regular to experienced users who need a push forward to dare try things themselves. Explain a bit deeper the posibilities and limitations of the browser. How to write your own macros, or change the browser appearance. Things that could have been in chapter 3 or 4, but have been moved til later to allow a longer explanation. The move also spare new users an overwhelming experience when trying to read the first chapters..

For this advanced chapter we need power-users to help out. At least advices and lists of points that ought to be addressed (if they don't contribute full chunks of text even).

Chapter 7: Reference

Here are the cold facts. Tables, lists, specifications, rules...