Thanks for the pointer. My main concern with that page and most documentation on mw.org (and the reason I started a personal list, so I could quickly find the stuff that matters to me) is that it's too massive, with too many links (as you noted yourself) and too much stuff highlighted, and I honestly feel a little overwhelmed reading it, finding myself following links only to find out that their target doesn't provide the information at the abstraction level that I expected.
I'll speculate a little, and suggest that the root of this disorientation happens due to not separating reference docs from tutorial docs, from what I'll call "guided overviews", and allowing each of these to clearly assume one of those identities. The list I've been putting together comprises reference docs, essentially index-like material that one can look up whenever one needs information on a specific part of mediawiki; There isn't much done in this regard. Brion once started a page which he called "Module registry<https://www.mediawiki.org/wiki/Modular_registry_of_components>", in 2009, which looked promising but it wasn't updated since. Tutorials should be mostly aimed at absolute newcomers: very short, and with a rather gentle learning curve; i.e., they should not introduce too many concepts too fast, nor assume a lot of previous knowledge. modular, interconnected compoments should be described in separate pages and hyperlinked so budding developers can RTFM, choose-your-own-adventure style. Currently very little of the docs fit that goal. Guided overviews are like Wikipedia articles: long, descriptive and mostly sequential texts describing an important component of the mediawiki infrastructure, such as the skinning system, or the messages API. I actually am not sure about the usefulness of such long guides, since newcomers will have a hard time following them, and experts will likely benefit more from index-like reference material. Maybe they should be broken down into interconnected bite-sized tutorials. I just came up with these categories, so there are probably many flaws to this analysis, but at a glance this seems like a good-enough overview of the state of our docs and what (in my humble opinion) needs to be done. Maybe my position won't be shared by many, but I'll be content if it causes some discussion about what overall strategy we need to implement to improve MW docs (which is undeniably considered important: let's not forget it's bug #1). --Waldir On Tue, Feb 26, 2013 at 10:14 PM, Quim Gil <q...@wikimedia.org> wrote: > On 02/26/2013 06:40 AM, Waldir Pimenta wrote: > >> I've been collecting a few links at >> http://www.mediawiki.org/?**oldid=651991#MediaWiki_**reference<http://www.mediawiki.org/?oldid=651991#MediaWiki_reference> >> that might be useful for newcomer developers to get a first overview of >> various components of the MediaWiki universe. >> > > Your help is welcome aligning your selection with > http://www.mediawiki.org/wiki/**Developer_hub<http://www.mediawiki.org/wiki/Developer_hub> > > By the way, do we really need 23 links under "Key documents", > after the 23 links contained at the "Overview" section, > following the first paragraph containing 5 links? > > No wonder someone like Atul keeps asking about what to read for a first > contribution. > > Let me know if those are helpful to you and what you think is missing from >> that list. Bear in mind that it's a work in progress, though. >> > > > -- > Quim Gil > Technical Contributor Coordinator @ Wikimedia Foundation > http://www.mediawiki.org/wiki/**User:Qgil<http://www.mediawiki.org/wiki/User:Qgil> > > ______________________________**_________________ > Wikitech-l mailing list > Wikitech-l@lists.wikimedia.org > https://lists.wikimedia.org/**mailman/listinfo/wikitech-l<https://lists.wikimedia.org/mailman/listinfo/wikitech-l> _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
