Zim Desktop Wiki description is confusing

[Tyler James]

"Zim is a WYSIWYG text editor. It aims at bringing the concept of a wiki to your desktop. For example every page is saved as a text file with wiki markup. Pages can contain links to other pages, and are saved automatically. Creating a new page is as easy as linking to a non-existing page. Pages are ordered in a hierarchical structure that gives it the look and feel of an outliner."

It states it is a WYSIWYG text editor, which no one knows what that is, and it doesn't even really explain it. Even the description of "It aims at bringing the concept of a wiki to your desktop" is not really that helpful to an end user. Describing what it actually does before what it technically is or what it aims to do would be more helpful. The second paragraph is a much better description that would not confuse a user.

[Sense Egbert Hofstede (sense)]

Thank you for helping with making Ubuntu better by reporting this bug. I'm accepting this as a paper cut.

[Vish (vish)]

Thanks for forwarding the bug to debian. You can forward your patch too. Makes it easier for the maintainer to review bug and patch at once.

[Jaap Karssenberg (jaap.karssenberg)]

Hi, I'm the maintainer of zim (upsteam). I agree that the description could be more clear and I'm open to suggestions. So far I have not seen a proposal for a text to replace it that seems better to me. If there is a concrete proposal I will consider it for the description in the upstream project page etc. Of course you are free to go ahead with a modified version in the ubuntu or debian packages.

In any case I would appreciate it if the reference to "wiki" style editing is kept in the description since I know from discussions with actual users that this is a common search term that makes people end up with zim.

Regards,

Jaap

[Chris Wilson (notgary-deactivatedaccount)]

Hi Jaap, what do you think of the following? I've written it to contain the word 'wiki' while briefly describing how a wiki works for those user unfamiliar with the term.

Zim is a graphical text editor which allows the user to maintain a collection
 of wiki-style interconnected notes. The text of each note can have certain
 important keywords highlighted with a link that provides a connection
 to another note named after the highlighted text. This new note can provide
 details on the meaning of the highlighted text, and can even contain links of
 its own.
 .
 Uses of Zim include:
 • TODO lists
 • Taking notes during meetings
 • Drafting blog entries and emails
 • Brainstorming

[Chris Wilson (notgary-deactivatedaccount)]

A patch for this bug has just been sent to Debian.

[Jaap Karssenberg (jaap.karssenberg)]

On Sat, Jan 8, 2011 at 5:53 PM, Chris Wilson <email address hidden> wrote:
> Hi Jaap, what do you think of the following? I've written it to contain
> the word 'wiki' while briefly describing how a wiki works for those user
> unfamiliar with the term.
>
> Zim is a graphical text editor which allows the user to maintain a collection
>  of wiki-style interconnected notes. The text of each note can have certain
>  important keywords highlighted with a link that provides a connection
>  to another note named after the highlighted text. This new note can provide
>  details on the meaning of the highlighted text, and can even contain links of
>  its own.
>  .
>  Uses of Zim include:
>  • TODO lists
>  • Taking notes during meetings
>  • Drafting blog entries and emails
>  • Brainstorming

I'm sorry, but I'm afraid that phrases like "certain important
keywords highlighted with a link" and "another note named after the
highlighted text" only make it more confusing. This sounds to me like
a technical definition of a hyperlink, but not really like a
description for end users. Wouldn't it suffice to say something like
"the text of each note can contain links to other pages as well as
simple formatting" -- I assume every user knows what a link is in this
internet age (you could replace "link" by "hyperlink"). Another
problem I have with this description is that it talks about "notes"
while the zim user interface consistently talks about "pages".

My counter proposal would be something like:

"""
Zim is a graphical text editor which allows the user to maintain a collection
of wiki-style interconnected pages. The text of each page can contain links
to other pages as well as simple formatting. Creating a new page is as easy
as linking to a nonexistent page. Pages are stored in a folder structure, like
in an outliner, and can have attachments.
Various plugins provide additional functionality, like a task list manager,
an equation editor, a tray icon, and version control.

[Chris Wilson (notgary-deactivatedaccount)]

Hi Jaap, thanks a lot for the feedback. I've submitted a revised patch that uses your version of the text.

[Oliver Joos (oliver-joos)]

I agree that it is more clear now. What I miss (even more now without the term "wysiwyg"): zim has a wysiwyg-editor and uses a simple (near-wysiwyg) wiki format to store the pages. Ok, this is quite common for wiki editors, but not for personal notes editors like Tomboy. zim is something between (or covers both ;-)

To differentiate zim from a text editors I'd add:
Each page can contain links to other pages, simple text formatting and inline images.

To emphasize zims open-minded storage format I'd add:
Pages are stored as wiki-formatted text files in a folder structure, like in an outliner, and can have attachments.

(I am not an English native. Feel free to find better words for what I miss)

[Jaap Karssenberg (jaap.karssenberg)]

Comment from debian package maintainer (copied here so I don't forget about it when reviewing):

---------------------------------------------------------------------
On Mon, 10 Jan 2011, Chris Wilson wrote:
> patch submitted

Thanks for your patches. First of I'd like to point out that the
description put in debian/control is based on the upstream description of
the project. So you probably want to submit this to upstream as well so
that they update their "readme.txt" and their website.

https://bugs.launchpad.net/zim/+filebug

Then your updated description is not correct:
> + Uses of Zim include:
> + • TODO lists
> + • Taking notes during meetings
> + • Drafting blog entries and emails
> + • Brainstorming

This is not a valid list in a description field. You need to have "2
spaces" at the start otherwise the lines will be wrapped together. And you
should probably avoid UTF-8 characters.

So it should be:

 Uses of Zim include:
  * TODO lists
  * Taking notes during meetings
  * Drafting blog entries and emails
  * Brainstorming

A few more remarks:

> + Zim is a graphical text editor which allows the user to maintain a collection

"which allows" is generally bad-style -> "text editor used to maintain"

> + of wiki-style interconnected pages. The text of each page can contain links

Why "the text" ? Each page can contain links.

> + to other pages as well as simple formatting. Creating a new page is as easy
> + as linking to a nonexistent page. Pages are stored in a folder structure, like
> + in an outliner, and can have attachments.
> .
> - This tool can be used to keep track of TODO lists or ideas,
> - to take notes during a meeting or to draft any other kind of
> - text (blog entries, important mails, etc.).
> + Various plugins provide additional functionality, like a task list manager,
> + an equation editor, a tray icon, and version control.
> + .

As a whole, it looks like an improvement though. Thanks for the work.

[ scratch 250 Kb of debdiff irrelevant for the description that I don't
understand ]

Cheers,
--
Raphaël Hertzog ◈ Debian Developer

[Jaap Karssenberg (jaap.karssenberg)]

So proposal including comments of Raphael and Joos becomes:

"""
Zim is a graphical text editor used to maintain a collection of wiki pages.
Each page can contain links to other pages, simple formatting and inline
images. Pages are stored in a folder structure, like in an outliner, and
can have attachments. Creating a new page is as easy as linking to a
nonexistent page. All data is stored in plain text files with wiki formatting.
Various plugins provide additional functionality, like a task list manager,
an equation editor, a tray icon, and support for version control.

Zim can be used to:
  * Keep an archive of notes
  * Take notes during meetings or lectures
  * Organize task lists
  * Draft blog entries and emails
  * Do brainstorming
"""

I feel we are getting towards a good simple description that is also technical correct and contains all the right keywords :)

Any more comments ?

Regards,

Jaap

[Chris Wilson (notgary-deactivatedaccount)]

"Each page can contain links to other pages, simple formatting and inline images."

I think we should avoid using the word 'inline' as only someone familiar with HMTL will understand what that means, so we should just say "simple formatting and images".

Apart from that, it looks good to me.

[Oliver Joos (oliver-joos)]

Ok, it is clear enough without 'inline'.
Thanks for merging my points. Looks good to me too now!

[Chris Wilson (notgary-deactivatedaccount)]

The attached branch contains the proposal detailed on comment 10, minus the word 'inline'. Ready for review.

[Jaap Karssenberg (jaap.karssenberg)]

New description adopted for source package control files, README etc.

[Jaap Karssenberg (jaap.karssenberg)]

Fix released in zim 0.50