Better documentation of demos/examples

[augustin]

Speaking of documentation:  https://trac.wymeditor.org/trac/ticket/208

I would like to create a new, custom button (with a text label in Chinese) which would automatically insert a template with several html elements with classes embedded within each other. (Basically, the template will be regularly used for standard reports to be posted on the site).

Is this possible?

How would I go about it?

I can document things in the wiki as I go a long if you'd like me to and tell me the most appropriate place to put this (a new page?).

(btw, how much can trac be customized? the type for this ticket is more of a support request than of an enhancement or a task. Can new types be added? A component 'wiki' or 'documentation' would be useful, too. At least, we can use this ticket to enhance the wiki documentation).

[augustin]

Ok. I found the documentation I needed here and its source code:  http://files.wymeditor.org/wymeditor/trunk/src/examples/07-custom-button.html

I was confused at first because the examples didn't work locally (see ticke 208).

However, the source says:

• File Name:
• 07-custom-button.html
• WYMeditor integration example - custom button.
• --->> See the documentation for more info. <<---

See which documentation? The one in the source code below that line, or online in the wiki.

Generally speaking, I think it would be better to have the help text actually displayed in the browser window of each example. Should I provide a patch to show you what I mean?

[augustin]

Another example. In this one:  http://files.wymeditor.org/wymeditor/trunk/src/examples/05-custom-dialog.html I spent half an hour trying to understand what was different and what feature was introduced. I couldn't reconcile the source code (links to gnu.org, etc.) with what I was seeing new in the browser (not much).

Here it is obvious that some text displayed within the browser explaining what to try and what to expect would have helped a lot.

[mr_lundis]

The "See the documentation for more info"-part is a piece of the standard file "header", and I'd say that it's referring to the wiki. That's not to say that the file contents is without interest, just that you will find that line is in the beginning of all source files.

Regarding the overall quality of the documentation, I see a lot of room for improvement. Feel free to help out any way you can! I think you should be able to edit the existing pages, as well as adding new ones. If not, just post your changes to a pastebin for now and I'll see what I can do regarding the permissions.

If you're writing some sort of tutorial or howto create a new page and link to it from "Contributed examples and cookbooks" (which would be more adequately named something like "Toutorials") on the wiki front page.

I'm all for adding some form of introductory texts to the examples. If you write some I'd be happy to include them.

Also, I've added a new "documentation" component. ;)

[augustin]

Thanks for the 'documentation' component.

I'm not very good with javascript and wouldn't be able to contribute much to the core of wymeditor (though I can help with the web site. See ticket #211).

However this kind of issue is simple enough for me to contribute a patch. I'll post one as soon as I have prepared one.

[augustin]

Let's start with some basic navigability before moving to the heart of the issue.

See this patch. Once you've committed it with eventual modifications, I'll follow up with another patch with the same changes applied to the other pages.

[augustin]

The second patch is a bit better. It changes the standard text 'see the documentation' to be a bit more explicit. I didn't include a link to the wiki because it might change in the near future. People will be able to find it easily anyway.

[augustin]

Also, the default "WYMeditor is a web-based XHTML WYSIWYM editor." on every page is a bit redundant. If it's ok with you, I'll remove it and replace it with actually informative text about what each example is supposed to show.

[mr_lundis]

I'll look into this tomorrow/this weekend. Cheers!

[mr_lundis]

I would prefer to leave the file comment alone, if we want to do any general project wide search and replaces. Also I think that the Back to the index link is better than Start: Index.

In other words I'd go with the first patch. But how did we end up at inter-demo navigation, when the real problem is poor documentation? I think the fact that you're having trouble understanding these examples is a much bigger issue than the lack of links between them (the browser comes with a back button anyway.)

I've sent jfh (the guy running the server and trac) an email about opening up the wiki, but no reply so far.

[augustin]

There is currently no navigation. The navigation patch should have been a no-brainer and makes it easier for me to work on the core of this issue.

The default "see the documentation" comment originally confused me. See above.