Use tags instead of categories

[nojhan]

IMHO, using categories to classify the code snippets may not permits several uses of acire. I would suggest to use a tag system, and permits a search by tags in the same way that del.icio.us shows it, rather than a single combo list.

The idea is to permits several classifications instead of a single one. For example, I could search for snippets about Gtk, but I could also try to learn something related to a given design pattern, and more probably, I would want to get snippets related to the use of the Decorator pattern in Gtk. With a single list, I can't restrict my search to composite categories.

A simple way to do that is to replace the actual combo list with a dynamic hierarchical view of tags. As an example, I put a screenshot of the del.icio.us extension for firefox that do more or less this kind of thing.

[Michael Mulqueen (michael.mulqueen)]

Perhaps tags would be better as a secondary way of finding things... I know they're very fashionable at the moment. Rightly so, they're great for categorising things like emails and webpages because they can contain so many different ideas in a single page. That and creating a comprehensive category-subcategory structure for all human knowledge/thought would be impossible, so a less organised approach is favourable.

Tags are really useful for categorising things that could fall into multiple classes. However when things fit into neat categories, it's better to use categories. If snippets fell into multiple classes, that would be a bad thing. They're meant to document a single concept - whether it's drawing a button or traversing a set of directories.

Where tags (or keywords) might be useful is as I've said above, a secondary location method. I can't say I can think of many usage cases for this. All snippets should be small and only have one purpose (as not to cause confusion), so it's unlikely that anything would ever need to be categorised in more than one way (other than through the use of categories and subcategories - see below).

Possible category structure:
Python → GUI Toolkits → GTK+ → GtkSourceview2
Python → Image Manipulation
Python → Web Frameworks → Django

[nojhan (nojhan-gmail)]

Let say I'm quite insensitive to fashion :-)

In fact, tags would create a hierarchical structure, as well as categories, but with deeper sub-levels. You may indeed consider that this is too complicated for some people.

But, for example, with the current snippet base, I find quite tedious to find all snippets related to the use of a tree widget in gtk. And what if I want to search all snippets related to data structures? If we had those two categories, where would you fill in the "Generic Tree Model" snippet?

By limiting categories to one or two levels, you somewhat move the difficulty from the developper to the user, as it becomes easyier to maintain coherent categories, but harder to find something.

If all snippets where really small and centered on a single purpose (which IMHO will not be the case, even right now I find this idea debatable), I would suggest using a drop-down menu (as now) along with a search field (instead of tags).

If, as I am convinced, snippets could be interesting for a user for a large number of reason that we simply can't imagine, what I would like to have is a hierarchical tag navigation system. The behaviour of such a system is exactly the same as a tree structure (as you suggest) but is far more easier to maintain with no difficulty cost for the user. However, one should keep in mind that tags should be chosen carefully, possibly in a list of existing one, by the developpers of the snippets.

[Ed S (edgar-b-dsouza)]

Well..

Though the SNIPPETS_CATEGORIES line in the snippet file header takes a comma-separated list of categories and shows the snippet item in multiple categories, I don't think it would be nice to overload it to include generic tags. For example, we could have tags like these for the PyGTK::Test Text snippet: "rich text", "editor", "inline picture data", "HSV to RGB", "color manipulation", "pango", "line numbering"... but since the main purpose of the snippet is not reflected in all possible tags for it, I doubt those can go in as categories. I think this makes a case for a simple tag system, since quite a few snippets have "scaffolding"/supporting code that is not the central focus of the snippet, but is nonetheless instructive to new coders.

I feel that new-to-the-stack programmers (like Jono describes at http://www.jonobacon.org/2010/01/30/connecting-the-opportunistic-dots/ ) would find a tag system (in addition to the current categories system) pretty useful - provided contributors help tag snippets properly :-). So this is a +1 for tags in general, but not for replacing categories - at least, not yet. That would mean, IMHO, a tag-search feature that lets users view items with multiple tags (ANDed, most likely).

So if you're willing to collaborate, here is a possible action plan:
- you make a personal bzr feature branch of python-snippets
- mod the snippet file headers to add a SNIPPET_TAGS line
- apply multiple tags to as many snippets as you have time for (leave a couple without, for code testing)
- push branch to your user dir on Launchpad and ping me to grab it

Given the above, I will try to mod Acire to:
- also parse tags, if present, on load of snippets
- add a Search dialog or frame/tab for tag search
- mod the main window a little (haven't figured out exactly what, but a tab seems like a good idea) to indicate items shown are search results, and to add controls to revert to display by category.

I can push the revision with these mods to my personal dir, then we can then request a simultaneous review of both branches so project leads and other users can try it out and decide if to accept.

So, shall we? :-)

[Jono Bacon (jonobacon)]

Sorry it took me so long to get to this bug. While I think a tags feature could be useful, I am conscious about clogging up too much of the snippets with meta data. I am wondering if we could solve this problem by instead encouraging commenting in the code and doing a fill text search across the snippets for key words. This would stop the tags being just a list of words and instead words that are in the context of explaining how code works. What do you think?

[Ed S (edgar-b-dsouza)]

The FTS sounds like a good idea, well worth a try (in a while). Do you have any preferred FTS engine for Python?

IF not, would Whoosh (http://bitbucket.org/mchaput/whoosh/wiki/Home ) be OK to try out later? Though there appears to be a package for it (https://launchpad.net/ubuntu/+source/python-whoosh ) there's also the possibility of including it directly in Acire's source tree, and avoiding another package dependency for Acire. Of course, the files in Acire's whoosh folder would need to be updated periodically, if this happens.