This page discusses how the front page, SiteMap, should look. The bottom half of this page lists decided issues, the top half is for discussion of open issues.
Here’s what SiteMap does:
In the past day or so, roland.walker has created several new category pages and a meta-category page, CategoryCategories. I thought, but don’t find it now, that categories were to be created only after discussion (where? here?). Doesn’t seem like a good idea that people should just be creating category pages willy nilly. – DrewAdams
At the top of SiteMap it says:
I think CategoryCategories is a tradition from the Portland Pattern Repository (the first wiki). It doesn’t seem quite so useful here since the SiteMap is supposed do double duty as a commented list of all the categories. I’ll read through the changes made and leave comments where appropriate. – AlexSchroeder
Yes, it says that about editing SiteMap, but it says nothing about proposing new categories (e.g., here), for discussion, before creating them. Perhaps it should (I think so).
Seems like there should be some discussion, or at least opportunity for discussion, before creating a new category page (or deleting an existing one). Category pages are at the meta level, and they determine the shape/organization of the wiki in a stronger way than do non-category pages. – DrewAdams
Categories should be meta-data, and meta-data should be able to be created willy-nilly. Much like any other content in a wiki. It’s about being fast, and then cohering things later.
I do find that categories, here, are not so useful, because they are less meta-data as opposed to hand-crafted links and index pages. If only somebody would do such a thing for the World Wide Web, it is sure to be useful and never go out of fashion, because the idea of automating such a practice [e.g., automatically compiling a list of all pages tagged with the category foo] is surely an impossible task and were it otherwise would undoubtedly lack the fine craftsmanship that a trained keypunch operator brings to such a task.
Seriously. The compilation of meta-data should be programmatic, not manual. That’s not the art - the art is in crafting the content.
That doesn’t mean to say that pages tagged foo should remain as foo - perhaps they should be tagged as baz. But as it stands now, it’s so bloody difficult to create a new tag that there’s very little chance for such a thing to gain traction.
It’s just too much work to research the available tags, select the right one, add it to the page, and then add a backlink to the tags index page. – MichaelPaulukonis
I sympathize with much that you say. However, the categories on this wiki are not tags, AFAIU. Tags are categories of a sort. But categories, in the sense used here at least, are not tags.
Categories here are intended to be relatively well defined and more or less exclusive. Not exclusive in their application — a given page can be in multiple categories — but exclusive in terms of their meanings. In particular, the wiki categories serve to provide a TOC or index on the SiteMap.
Tags are freely creatable and applicable - they are ad hoc. They serve as shortcuts for search. We do not have explicit tags on this wiki, but search should pick up relevant terms. If it does not then that could be seen as a failing in search.
We could perhaps consider adding a separate tagging facility; dunno. (I’m no expert on this, FWIW.) – DrewAdams
The reason I started using categories the way they are is that I find it extremely hard to navigate hypertext without a hand-crafted structure. The original wikis relied on full-text search to navigate categories, and it worked, more or less. It was hard to see which categories existed. It was slow to use. When presented with a list of page names, it was hard to figure out which ones were relevant to my interest. Taking a cue from Emacs’ Info structure, I decided that having a hand-crafted structure where each page of the menu is annotated is much easier to use.
Writers can still write pages and create categories willy-nilly. And there will be diligent peer reviewers like Drew fixing the stuff later. I still want to encourage writers to spend the time and do it right, however.
I have no strong feelings about it, but why? Why not keep all categories with the prefix
Category, for consistency? For one thing, searching for
‘category’ finds them all as the first hits. What’s the reason for treating this category exceptionally?
If your point was that we do not need such a category, then the response should be to just get rid of it, changing all refs to it to refs to
CategoryCode. And then perhaps have an anchor on the CategoryCode page for BatchMode. Maybe that’s in fact what you meant? – DrewAdams
I meant the latter. Shall we demote it from a category to a regular page? – AaronHawley
OK by me. – DrewAdams
Yes we should. ☺ – AlexSchroeder
Categories are important to discovery and navigation. The SiteMap page is the canonical listing of all categories. It is there that you look, to see what categories are available for classifying your new page. However, the category names are abbreviated on the SiteMap. That helps readability, but it obscures the list of categories for editing purposes. The SiteMap should contain a brief mention such as the following:
Yes, it’s CreateNewPages, and I already added it there. I still think it’s needed also on the SiteMap. Many people will create pages without passing through CreateNewPages. They are, however, likely to stumble upon the explanation at SiteMap. – DrewAdams
Most of the categories under the pseudo-heading “Customize” are general and not necessarily about customizing at all. It was quite misguided to group things this way. Just look at those category pages (Windows, Keys, Mouse, Display…) – you will find general information and lots of other material that has nothing to do with customization. Keys is not more about customization than is Menus, for instance.
This category organization is incorrect, misleading, and unhelpful. “Customize” should be removed altogether. Customization of different kinds of things (keys, faces, frames, etc.) is found within the categories for those features. Customization is everywhere in Emacs, and nearly everything is customizable. List the features here; users will look for their customization within their categories. – DrewAdams
Well said – indeed “nearly everything is customizable.” I agree that the category is not selective enough. – AlexSchroeder
In my last edit of the SiteMap, I accidentally removed the headings when I was only trying to change the link format for all the categories.
How about we give this format without a table of contents a try? Did anyone think the navigation was useful? I predict a lot of visitors need to scroll the page anyway to get an idea of where they should find what they’re looking for. I know there are opinions that the SiteMap isn’t well organized anyway. This would ease scrolling?
If only there was time for a usability study… – AaronHawley
Discussion should occur before a change is made, not afterward. I wonder how one “accidentally” removes “
==” both before and after each individual heading?
Now, people should compare the current version with the version before your change, by looking at two browser windows (not just a
My opinion before comparing: It doesn’t make much difference; it’s OK as it is now.
My opinion after comparing: the TOC helps, and should be restored. Especially because the categories are numerous and not always well-defined. A TOC helps you see at a glance how the page is organized and what the “categories of categories” are.
Yes, people will often scroll the page, regardless. That does not mean that it isn’t helpful to let them know what super-category a given category is in. And no, this does not “ease scrolling”. It simply makes a global view more difficult. Being obliged to skim the entire page does not imply “easing scrolling”. Just one opinion. – DrewAdams
Aaron’s “accidental” change should have been reverted, pending discussion and a consensus. Instead, the previous version is now lost (so you cannot even compare). So much for site-map “discussion”. – DrewAdams
There is no category for highlighting. Currently, from the SiteMap, pages about highlighting text can only be found by going to Customize, then Faces, neither of which is suggestive for someone looking to, say, highlight matches for a regexp in a buffer – that is not really about customizing. Highlighting can mean several things, including standard font-lock and everything in HighlightTemporarily. How about adding a [[Highlighting?]] category? It could be situated next to category HideStuff, for instance. If no objection is raised here, I’ll do this. – DrewAdams
I agree, a new category is necessary. – Alex
My opinion: Add CategoryHighlighting? to the pages that currently have CategoryFaces, but only if they seem to be about highlighting – case by case. It’s a judgment call. But I’d think that most, if not all, would continue to also be in CategoryFaces.
We can view highlighting as a subcategory of faces or not; either would work. Probably not is better, since much to do with faces doesn’t really involve highlighting.
But the important thing is to not force this stuff to be part of CategoryCustomize. I don’t even think category Faces should be under category Customize. It’s not because you can customize faces that that’s all that faces are about. – DrewAdams
I predict things in CategoryFaces that have “highlight” in their name will be in highlighting--HighlightTemporarily, HighLight, HiLock, HighlightCurrentLine, HighlightCurrentColumn, HighlightEndOfBuffer, HighlightSymbol, HighlightParentheses. This might be a mistake. There are many things that have similar functionality but probably won’t make it just because they aren’t named highlighting--ReBuilder, EightyColumnRule, VisibleMark, ShowParenMode, TransientMarkMode or IncrementalSearch. CategoryFaces obviously doesn’t even cover these pages.
Further, “syntax highlighting”, or FontLockMode as it’s known to Emacsen users--isn’t likely well served in a highlighting category because it’s not predominant a connotation, see Highlight Interactively. There are pages on the site narrowly focused on highlighting that deserve this category, but we need to keep in mind that highlighting is a user interface technique that spans a lot of Emacs features. So, even for the “highlighting” examples above, the best solutions are probably still CategoryRegexp, CategoryRegion, CategoryDisplay, CategoryEditing, CategoryParentheses.
I don’t have a proposal, but I’m saying that “case by case” may backfire. I know many pages are cross-listed in two or more categories in an effective way. However, “highlighting” might become such a catch-all that it could become diluted and not useful. – AaronHawley
Well, thinking about every page individually makes sense. We just need to define what “highlighting” is going to be about. I’d say that highlighting is about manually highlighting things (ie. not Font Lock), or automatically highlighting particular user interface features (a particular column, the current line, the end of the buffer, nothing mode-specific). – Alex
I think you’ve defined highlighting well. So, would that put ReBuilder, EightyColumnRule, VisibleMark, ShowParenMode, TransientMarkMode and IncrementalSearch in the category? With that, I think it might still be too broad. My concern being “highlighting is a user interface technique that spans a lot of Emacs features”. However, I guess there’s no other way to do this but to include them all.
Here’s a proposal for the category’s description.
Feel free to delete what I have and make a comment containing your latest modification of the above. – AaronHawley
The SiteMap is less useful than it was. It’s fine to try to group things into subcategories, but only if those groups make sense and are helpful. There is lots of stuff under Customize, for instance, that is not necessarily about customizing Emacs. E.g., if you wanted to learn about manipulating and navigating among Emacs windows, you wouldn’t think to look under Customize. A related problem is the lack of parallelism for categories: some are verb forms corresponding to things you might do (“customize”); others are noun forms corresponding to Emacs objects of different kinds (“commands”). Both task-oriented and object-oriented organizations can be useful, but they should generally be separated. No need to be anal about this, but the current mishmash is particularly unhelpful. – DrewAdams
I’m not sure what the problem is. Do we have too many categories per page? Or do we need to support category synonyms (or more redirections)? Or do we just need to concentrate on the categories we actually use on the SiteMap and use those more consistently? – Alex
Added descriptive text about where to find categories and external libs (it wasn’t obvious, as the Categories pages linked to on SiteMap seemed to me and others (at first glance) to be general emacs info, and not external libs). I’ve used the emacswiki for a long time (and have posted libs here) and it used to be more apparent where to find libs. – [[trogdoroeu?]]
I agree with what Aaron has done. [[trogdoroeu?]]’s concern seems to be letting people know that they can find source code and especially links to source code, including code at off-wiki URLs, on the various category pages and other wiki pages. Linking to ElispArea up front is important, but it doesn’t really take care of [[trogdoroeu?]]’s concern. I’m not sure how best we could do that. I tend to think that people will figure that out, but s?he obviously got the opposite impression. – DrewAdams
I think it might be good to put the different elisp sources on equal levels. As it is now ElispArea seems to be superior - which is true for some elisp files but not for others. Therefore elisp libraries that are not mentioned in ElispArea might go unnoticed to novices.
I suggest this:
Yes, maybe they should be listed there. But I think there is a problem with that list. It contains single files and there is no notion of packages there. CEDET is not mentioned at all, JDEE is mentioned as jdee.el and nXhtml as nxhtml.el. These should be better mentioned in another way.
The list is really structured around single elisp files. It is problematic to find related files and all files are not mentioned there. – LennartBorgman
I’m not sure what the conclusion of this discussion is. No problem? Must do something? What? – Alex
I actually didn’t think there was a problem. EmacsLispList lists many “packages”. And if not, EmacsWiki – as a project – has been the making up by documenting “Emacs Lisp packages” – a better phrase than “Emacs packages”, perhaps. – AaronHawley
Yes, Emacs Lisp Packages seems like a better name.
But I really did think there was a problem. How do you expect a new comer to Emacs to find those packages listed on EmacsPackages now? – Lennart
But packages of elisp code, like for example CEDET, are not at the same level as individual elisp files. There a much more effort put in these packages and the users deserves a good way to find them. I do not know how many elisp files there are here, but there are surely just a few packages with elisp files that are written to work together. – LennartBorgman
These are some conclusions from past discussions.