GSoC/GCI Archive
Google Code-in 2011 KDE

User documentation for setup and use of Kmail

completed by: Subhashish

mentors: Bertjan

Kmail is being adopted by more users and should have simple to understand, easy to follow setup and use instructions for people wanting to use it with existing webmail or office accounts.

Expected results: Kmail User documentation in Userbase
Prerequisites: Being able to give clear instructions and proofread.

A first start is made here:

The goal if this new task is to bring this document to the next level. Here are a bunch of guidelines/comments where improvement is needed:

Here a summary of things that needs to be improved in my opinion:

    1. First of all, keep in mind that you are not writing for your classmates. There is a broad range of people that will read this document but the larger part will likely be people that work in a professional context. This means that you should try to write professional and realistic. For example: KMail is indeed awesome but it does not do everything I need it to do (it doesn't bring me coffee for example and it also doesn't read my mind =:). Another example is the usage of WillSmith and JamesBond in the part about identities. Not many users will be able to identify themselves with this situation (and will smith never played James Bond by the way =;).
    2. The introduction. It is still too brief and it is not adjusted with respect to my earlier comments. Let me give an example of a better text here: "In this guide you will learn how to make kmail ready for basic usage. First we will introduce identities, what they are and how to create new identities. Next we will move on to the configuration for sending and retrieving email. Finally, we will give a brief overview of the other configuration options that kmail provides". Note, you should of course not literally copy this text as it just serves as an example for you. I try to make a couple of points clear here: first notice that I try to define the scope of the document (that is, the reader will not learn everything, but only the things needed for basic usage). Second, I give step by step an overview of what will follow in the document. Finally, I tell the user *what* he will learn (as opposed to how these things actually are done).
    3. How to setup KMail: You really should start this section with the story about identities. (You now postponed this to accounts). Look at my previous comment about identities. Give a concrete example where multiple identities apply. Also note, multiple identities here rely is about the same person having different functions, not about different persons. Again an example of how you could start this section: "In our daily life we often perform tasks with different hats on. From eight to five we do our daily work and therefore send email with our business address. In the meantime we also communicate with our familly and friends but of course use our private email address. Furthermore, you might be the chairman of the local sportclub which requires you to send mail from yet another address. These different functions are represented by identities in KMail. Indentities allow you....... and so on and so on". Again, don't copy this text but use it as a guide to make clear what the section is about.
    4. Remove the three information boxes in the identities section. These are incomplete and also unneeded when you have properly introduced identities as I proposed above.
    5. Account: Here the text that talks about identities should be removed as this was introduced before. For some people having one identity might be perfectly fine, stick to the facts. Just tell that this section is about creating an account for receiving mail and that it will be coupled to (one of)the created identities. Furthermore, the reader does not need to choose a type of an account. This is not something random but depending on what his email provider dictates. So the user should check his provider letter containing the settings for sending and receiving email.