Roger wrote: ... I just now started a page to document MediaWiki user interface customization. You can help write this page: http://www.mediawiki.org/wiki/Manual:Interface
Thanks, Roger.
Great start. Now, where's the MediaWiki "table of contents" scheme into which your "Manual:Interface" page fits? Searching MediaWiki.org for "interface" brings up: 1st = http://www.mediawiki.org/wiki/Category:User_interface ... nope ... skipping all the unrelated noise ... 40th(!) = http://www.mediawiki.org/wiki/Manual:Navigation_bar ... some relevance ... and so on! I didn't look further. How would anybody find Manual:Interface?
I searched for "manual" and get the "manual" page at http://www.mediawiki.org/wiki/Manual ... which has NO table of contents for any "manual" for MediaWiki. Doh! Likewise http://www.mediawiki.org/wiki/Project:Manual ... but http://www.mediawiki.org/wiki/Manual:Flat_namespace contains this thoughtful tease from http://www.mediawiki.org/wiki/User:Rogerhc (hey, that's also you!):
"... * Flat namespaces are easier to navigate, * The fewer levels of hierarchy the better when dealing with collaboration, * People can't collaborate if they can't find what they are looking for ... An encyclopedia is a classic flat namespace. So is a dictionary. The names of pages in MediaWiki.org are not encyclopedic nor dictionary like because the topic of MediaWiki is narrow and deep, not shallow and wide like an encyclopedia or dictionary. So keeping the page namespace on MediaWiki.org flat and easy to navigate is not as easy as keeping the page namespace of Wikipedia.org or Wiktionary.org flat. But the need to keep taxonomic hierarchy on MediaWiki.org as simple as possible and flat as practical is important. It is management of information complexity. Subpages may hurt site usability more than help because it can be hard for newcomers to guess where in the hierarchy something can be found and hard for veteran users to remember how to type out the exact hierarchy under which a page is located. Categories and other labels should be kept as short as possible so that bunches remain easy to read and navigate at a glance and individual instances remain easy to type from memory into a page...."
Hmm ... easy to navigate a flat space? In what city do you live?!? ;-) In the real world, I drive my car on a linear (not flat) surface of the globe, but I use a reference road map to find destinations and plan my trip, I have many ways to search through preview resources, and I also have alternative ways to get from point A to point B: air, ground, water. I don't see such resources in MediaWiki's "simple" search and no automatic meta table of contents.
Special:Allpages is a start, but only brings up pages in the "Main" namespace, right? But, at MediaWiki.org, there's also: Talk, User, User talk, Project, Project talk, Image, Image talk, MediaWiki, MediaWiki talk, Template, Template talk, Help, Help talk, Category, Category talk, Manual, Manual talk, Extension, Extension talk! 18 additional namespaces where disconnected pieces and parts of any "MediaWiki setup-and-configure instruction manual" may lay!
Does anyone know how to really list ALL Allpages - as that might be a great place to start building a total table of contents that grabs and organizes such disparate pages as are scattered across, say, "Manual:..." and "Project:..." and so on, all related in content, but not related any other way? Someone at http://www.mediawiki.org/wiki/Project_talk:Support_desk#MediaWiki_Overvi ew_-_database_structure asked what the MediaWiki/MySQL database structure looks like, and the answer is elsewhere at http://www.mediawiki.org/wiki/Manual:Database_layout. How do we plan to coordinate such disparate contents from "Project talk" and "Manual:nnn" ... and make it findable and easy to navigate?!?
If anyone thinks the "search" box is the answer, they're dreaming! Why do we think there's such scattered info as it is? Because the "search" box results are not very sophisticated. I've expanded mine to show: Hits per page: 100, Lines per hit: 20, Context per line: 100, and I scan the entire list before giving up. Is anyone else that patient with the MediaWiki "search" feature results before Googling, instead?
In the computer resource world, I'm used to controlled vocabulary hierarchies like http://www.controlledvocabulary.com/. Photography is my second language, and I have thousands of image files to catalog and share, so hierarchies like "cat is under animal and mammal and domestic and color and date and location" are no problem for me and any relational database to manage .. hey, isn't MediaWiki built on a relational database?
I guess when I'm looking for the pieces and parts of "...a basic wiki setup-and-configure instruction manual...", analogies like "road map" overview are also appropriate.
However, one of us is going to have to write an exhaustive, hierarchical table of contents for all those pieces and parts of MediaWiki setup-and-configure instruction manual we find all over the place, combine duplicates, identify gaps. I'm just not experienced enough to see MediaWiki clearly through what for me is still quite thick fog. Does anybody else have a sense of how to impose a structure on the vast resources at MediaWiki.org?
-- Peter Blaise (see http://www.mediawiki.org/wiki/Special:Contributions/Peterblaise for my paltry contributions so far, mostly just questions!)
I think the main problem here is that you're seeing MediaWiki as a software platform designed like Quicken, with a single purpose in mind. MediaWiki is designed with a single purpose in mind, but that purpose is Wikipedia: The people who use the software for their own purposes are important too, but they're not what development is centered around. And since development comes from many directions and people, the focus tends to be on making the software work, not on making it orderly for people who are rummaging through it.
On 6/13/07, Monahon, Peter B. Peter.Monahon@uspto.gov wrote:
However, one of us is going to have to write an exhaustive, hierarchical table of contents for all those pieces and parts of MediaWiki setup-and-configure instruction manual we find all over the place, combine duplicates, identify gaps. I'm just not experienced enough to see MediaWiki clearly through what for me is still quite thick fog. Does anybody else have a sense of how to impose a structure on the vast resources at MediaWiki.org?
I think I see why the information about MediaWiki is less-than-ideally organized: The people who are really interested in documenting things (like you) don't necessarily have much knowledge of or experience with the software, and the people who really know a lot about it (like Rob Church) would rather be working on the software than writing documentation for it. If you really want to change this, then you're going to have to unite the two parts, either by learning enough about MediaWiki to document all the things you want to document, or by getting the people who really know the software well to help you. Judging by the responses to your emails, it doesn't seem like those people are going to jump forth and help you along every step of the way, so I'd suggest you start poring through every bit of documentation you can find, whether on Wikipedia, meta.wikimedia.org, mediawiki.org, the software files (/includes/DefaultSettings.php has a lot of neat stuff), third party how-tos (there seem to be all sorts of articles scattered through the web on various MediaWiki subjects, if you do a Google search), existing MediaWiki implementations, and anywhere else you can think of. I've been running a wiki for a year now (with some previous experience as an end-user), and I think I have a pretty good grasp of most of the visible concepts of the software; I don't know nearly as much as I'd like about all the code and whirring gears that make everything work, but you don't necessarily need to know all about that to document things as a sysadmin.
If the idea of transforming yourself into a MediaWiki guru so that you can restructure the documentation is too daunting, then you should abandon your visionary approach, find the specific tasks you need to do, get the help (paid or otherwise) you need to accomplish them, and document your methods as you go.
Good luck, whatever you decide.
I think I see why the information about MediaWiki is less-than-ideally organized: The people who are really interested in documenting things (like you) don't necessarily have much knowledge of or experience with the software, and the people who really know a lot about it (like Rob Church) would rather be working on the software than writing documentation for it. If you really want to change this, then you're going to have to unite the two parts, either by learning enough about MediaWiki to document all the things you want to document, or by getting the people who really know the software well to help you. Judging by the responses to your emails, it doesn't seem like those people are going to jump forth and help you along every step of the way, so I'd suggest you start poring through every bit of documentation you can find, whether on Wikipedia, meta.wikimedia.org, mediawiki.org, the software files (/includes/DefaultSettings.php has a lot of neat stuff), third party how-tos (there seem to be all sorts of articles scattered through the web on various MediaWiki subjects, if you do a Google search), existing MediaWiki implementations, and anywhere else you can think of. I've been running a wiki for a year now (with some previous experience as an end-user), and I think I have a pretty good grasp of most of the visible concepts of the software; I don't know nearly as much as I'd like about all the code and whirring gears that make everything work, but you don't necessarily need to know all about that to document things as a sysadmin.
I've avoided this thread, but I think you bring up a very good point here, and I'd like to say one thing and then continue to try to ignore this thread.
Peter... If you want MediaWiki documented to the point you find acceptable, why don't you hire someone with the available knowledge to do so? Complaining to volunteers about their documentation not being good enough is rediculous. Do you go to a soup kitchen, and complain that their soup isn't the quality of a four star restaurant?
We understand that our documentation isn't up to par. We try to document as well as possible, but we have development work to do, and most of us have other jobs as well. If you want better work out of us, motivate us with money. You'll be helping yourself, and providing help back to the community. Either way, it would be far better than trolling this thread, and wasting our time.
If you want to hire someone to do proper documentation, please start a new thread offering to hire a knowledgable person with technical writing skills.
V/r,
Ryan Lane
mediawiki-l@lists.wikimedia.org