Some Thoughts For Discussion
- Would it be helpful to get rid of display of the somewhat awkward "Cmd" prefix for commands, and simply do a better job of separating the sections that cover concepts and ideas from those that discuss specific commands?
- Empty links discourage. Could we eliminate them sooner rather than later? Yes, they are helpful initially for maintaining some structure, but people do get bummed out when they follow a link for an interesting topic and end up with nothing. If there are too many of these, then they may quit and go home before finding the real content -- and that would be a shame since there is now plenty of real content.
- For those coming into the Wiki for the first time, we should insure that the most useful content is out front and on top. Right now the TOC has an awful lot of blank links, so having it on top isn't so helpful as a starting point for nagivation. In contrast, the Categories, Script Library, and PyMOL Commands sections all seem like pretty good starting points.
- For people (like me) who don't know the first thing about Wiki's, more "newbies click here to learn" links would help ease the transition...
- Categories & subcategories confuse me. The resulting titles baffle. For example, Category: Using Pymol Objects and Selections Working with Objects. Shouldn't there be another colon in there? Category: Using Pymol Objects and Selections: Working with Objects Is this just a Wiki thing?
Warren (BTW: Please don't weight what I write too heavily here. With respect to PyMolWiki, I am just another user -- and a clueless one at that).
Begin Inchoate's Comments To Warren
First off, thanks for the post. I always welcome better ways to work and organize information. I don't claim to know any more than anyone else, I just took the initiative for PyMolWiki.
Warren, you're completely right. Something needs to change, to make this more usable for people. I tried to organize the PyMol information via the user manual and user comments. Imposing a hierarchy on a system that doesn't really want one, isn't such a good idea, or my imposition was implemented incorrectly. The link names need to be MUCH shorter: take a look at http://wikipedia.org. They have 500,000+ pages and they have short link names. I tried to make a hierarchy so that if three such people come in and look up "rotate" that they go to the right page. That is, there's "rotate," "cmd.rotate," and camera independent rotations and whatnot. We have name ambiguitities. Do we just make one big page with "rotate" and include all its information there, or do we make "rotate" a category and dole out the pages to the category?
I'm ambivalent towards empty links. They remind me of what basic concepts that need filling, but are annoying if you're searching for info. and there's nothing there.
As far as the comments on categories and subcategories, as I understand it, you can't use double ":"s in names. You have categories and then something is made a subcategory by claiming that is'a category of a category. Kinda' strange.
I do think organization is good. My way was seemingly obfuscated. Don't you think PyMol commands should somehow be lumped into available categories? Changes to be made from my POV:
- Much shorter link names
- Kill the hierarchy?
- How to use the Wiki Intro
I tihnk I found the problem, and I might be able to solve it. I just made things hard by including the hierarchy in the naming scheme, when that's not appropriate. I think the hierarchy's still very important; however, I think the name-ambiguity problem is not solved via this method.
I've made lots of changes:
- I actually took Warren's suggestion on epmty links. I sifted through the TOPTOC and made empty links normal text -- but left them there in case anyone wants to make them links by adding content.
- Also, I've gone through all the commands and removed the Cmd prefix. The commands, and all commands buried in modules should be easy to create by simply making a new page as, for example, "Editing.Get_Dihedral" or whatever.
- The names of the links should be MUCH easier to handle, and are far less obfuscated.
MediaWiki-style organization is starting to make sense. :-)
Inchoate 00:48, 6 May 2005 (CDT)
A singular vote from TStout
One thing that I think has been missing from the manuals and the Wiki (and manuals for many other programs, I might add) are copious EXAMPLES of how to actually use a command. Speaking as an advanced-dummy, I find it terribly imposing to be presented with something like "cmd.select(string name, string selection)" as an explanation for how a command works. "How does that translate into what I should type?" is the polite version of how I end up reading such things.... :) Recently, I have noticed more "real" examples being entered into the Wiki: THANK YOU! The example given just now also comes complete with an Examples entry with things like:
select near , (ll expand 8) select near , (ll expand 8) select bb, (name ca,n,c,o )
For beginning users, such entries are invaluable. In fact, I would extend that to say that an inverted approach to manual/Wiki writing would be even better for the beginning PyMOL user: organize around how to accomplish the usual tasks, not around a glossary of all the possible commands......That said, a HUGE thank you to all who are putting in so much time building, maintaining and getting this to critical mass so that it becomes the invaluable resource it clearly is headed toward! -Tom