User:Egfrank

From MediaWiki.org

[edit] Improving MediaWiki documentation

One of the problems I've noticed with the MediaWiki documentation is that information on customization is scattered and missing some important matters. This is a real pity because as I've gotten to know the code base I am increasingly impressed with the organization and customization options.

This lack of documentation has two disturbing side effects that are likely to become increasingly problematic as MediaWiki gains attention and more companies start using it for their intranet and websites:

1. Underestimation: From time to time on the support desk there are people who say "The problem with MediaWiki is that it doesn't do X". Of course, MediaWiki does X, but the information is hard to find. As a sometimes support helper I find myself frustrated because I can't even point the user to a Manual page.
2. Hacking: I've had a chance to look at most of the extensions. Some of them unnecessarily patch core code and I strongly suspect that lack of documentation is the reason. Documenting the hooks in Manual:Hooks and its sub-pages is an important start, but people new to the system also need how-to articles that list the hooks they need to consider when they want to do X.

I am trying to do my bit to improve things, mostly by working on customization overview articles and improving the categorization of extensions and articles on customization. I bring to the table three skills/loves that I hope will help:

• a love of teaching and the learning process
• fluency in reading source code in many different languages
• 20+ years working on and off as a software project manager, hands-on developer and system administrator.

If I make mistakes, please be patient with me and add your thoughts to my talk page or the appropriate article. MediaWiki is a complex bit of software and it has a rich community of developers, administrators, and users with many different understandings of the software, how it should be used, and how it should be understood by others. It takes time, effort and lots of feedback to get it right. Thanks.

[edit] Followup

• queries on Category_talk:Extensions.

[edit] To do

• add integration targets for Category:Social bookmarking extensions
• New breakdowns
  • Category:Extensions by core system
  • Category:Extensions by content source - remote, filesystem, db, images(terminology?)
  • category:Extensions by communication channel
• Questionable categories (cleanup/merge/redirect needed?):
  • Category:Log extensions
  • Category:Embedded extensions
  • Category:Navigation extensions
  • Category:Template extensions
  • Category:Media handling extensions - has lots of stuff that probably belong in subcategory (e.g. tags that don't use $wgMediaHandlers)
• Categories to empty/rename: Category:Extensions by category, off-site extensions category
• How to categorize?
  • lists/tables generated from page content, files on system, database resources, etc - generated page content? too general? extensions by content source?
• Documentation pages
  • Merge of info on Category:Extension with Manual:Extensions; propose split of Manual:Extensions into user, admin, and developer sections a la Manual:Skin
  • Technique articles: Manual:Search extensions, Manual:Media handler extensions - update template to point to these when done. Needs to cover both MediaWiki's built in system and alternatives (e.g. embedding HTML to use the browser's add-ons)
  • Other: Manual:Security, Manual:Search, Manual:Multimedia, Manual:Media handlers (redirect to Media handler extensions - too technical a search term).
• Questions to ask/Proposals
  • Warnings for extensions that embed scripts (can either be source of XSS attacks against sites receiving feeds and/or danger to host site if executable on that site) - on what forum should this be discussed?
  • Manual organization - seems that someone once had the idea of breaking up MediaWiki into components and then adding categories and articles for each component. Does this work? What gets lost if this is the only organizing principle? Is anyone still committed to it? Should they be?
  • Category:MediaWiki Development - what is this for? how is it different from Category:MediaWiki technical documentation and Category:MediaWiki components? Where should the category I added Category:Customization techniques fit in? Is it redundant?
  • Do we want to consider Extension namespace articles to extensions that make their source code available on line in uncompressed format? It is in the spirit of open source and if we can't police these extensions, people should at least be able to review the code for obvious problems before they have to download it. Egfrank 08:40, 21 September 2007 (UTC)