Re: [Wikitech-l] Developer Hub simplification
Thank you Waldir for your analysis of http://www.mediawiki.org/wiki/Developer_hub On 02/26/2013 04:01 PM, Waldir Pimenta wrote: My main concern with that page is that it's too massive, with too many links and too much stuff highlighted, and I honestly feel a little overwhelmed reading it I agree, and this is exactly the opposite of what a Developer Hub should be. 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. And more: that overwhelming page focuses on PHP / MediaWiki core / extensions while all the newer areas of development are still missing. A Developer Hub must be the hub for all developers. Following with your proposal, we could have: Developer Hub: a general overview with a very focused selection of links to send people to appropriate places. Less is more. /Get started (or similar name): intro for newcomers with relevant links. /Reference (or similar name): what developers need on a regular basis. Developer Hub and Get started should be more concise and visually pleasant, satisfying new developers. Reference is for usual suspects, so it could have more beef and links in order to have everything in one place. Do you think this makes sense? Should we start discussing at http://www.mediawiki.org/wiki/Talk:Developer_hub ? -- Quim Gil Technical Contributor Coordinator @ Wikimedia Foundation http://www.mediawiki.org/wiki/User:Qgil ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Developer Hub simplification
On Wed, Feb 27, 2013 at 3:39 PM, Quim Gil q...@wikimedia.org wrote: And more: that overwhelming page focuses on PHP / MediaWiki core / extensions while all the newer areas of development are still missing. A Developer Hub must be the hub for all developers. Agreed. Following with your proposal, we could have: - Developer Hub: a general overview with a very focused selection of links to send people to appropriate places. Less is more. - /Get started (or similar name): intro for newcomers with relevant links. - /Reference (or similar name): what developers need on a regular basis. Developer Hub and Get started should be more concise and visually pleasant, satisfying new developers. Reference is for usual suspects, so it could have more beef and links in order to have everything in one place. Do you think this makes sense? Should we start discussing at http://www.mediawiki.org/wiki/**Talk:Developer_hubhttp://www.mediawiki.org/wiki/Talk:Developer_hub? Yes, that makes sense, though we need to think about how the pages in the Manual namespace would fit this arrangement. Other developers' opinions (seasoned and newcomers alike) would be quite valuable to prevent wasted effort due to overlooking details like these. Also, I agree that it would be best to have this discussion at Talk:Developer hub. Perhaps copying this thread there (or linking to the mailing list archives) would be a good idea, to provide context. --Waldir ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Developer Hub simplification
Good that least you and me agree on the basics. :) On 02/27/2013 08:50 AM, Waldir Pimenta wrote: Also, I agree that it would be best to have this discussion at Talk:Developer hub. Perhaps copying this thread there (or linking to the mailing list archives) would be a good idea, to provide context. More feedback and details are welcome at http://www.mediawiki.org/wiki/Talk:Developer_hub#Developer_Hub_update -- Quim Gil Technical Contributor Coordinator @ Wikimedia Foundation http://www.mediawiki.org/wiki/User:Qgil ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
[Wikitech-l] Developer Hub simplification (was Re: Gsoc 2013 guidelines)
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 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 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 ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Developer Hub simplification (was Re: Gsoc 2013 guidelines)
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 registryhttps://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_**referencehttp://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_hubhttp://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:Qgilhttp://www.mediawiki.org/wiki/User:Qgil __**_ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/**mailman/listinfo/wikitech-lhttps://lists.wikimedia.org/mailman/listinfo/wikitech-l ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
