Developer Advocacy/Developer Portal/Content Draft/Feedback

From mediawiki.org
This feedback page is closed. Thanks everyone for your feedback!
In June 2021 we consolidated and summarized all feedback received on this page and via other channels and finalized the initial content draft.

See Developer Advocacy/Developer Portal#Timeline for the full timeline.

For the content rendered per section instead, see this HTML page.

Idea/concept: Do you think this kind of portal would help you or others to find relevant documentation?[edit]

ℹ Consider existing and future technical contributors with different levels of expertise.

  • Add your comment


Structure: Does the general structure make sense to you?[edit]

ℹ You can see the structure in the table of contents.

  • I have a few different comments; I wasn't sure to put them all, so I guess I'll put them here. So: there's obviously a ton of text here. It seems like it was a conscious decision to try to put everything on one page, but I'm not sure it was the right decision; this is a lot for anyone to read through. Maybe it would be better to have high-level headers linking to other pages? Although maybe just having less text would solve the problem.
Tied in with that, the whole structure of "Header > Description > Link(s)", though well-put-together, sometimes seems unnecessarily wordy. In some cases, it seems to be essentially the same information expressed three times, like "Explore existing MediaWiki extensions deployed on Wikimedia servers > List of all extensions which are deployed on Wikimedia servers > Category:Extensions used on Wikimedia". Simple lists of links (like what the main page has) may work better.
The "Contribute to the MediaWiki software platform and stand-alone applications" section may be the strangest section on the page. A few of the links are indeed relevant to potential new developers, like "How to become a MediaWiki hacker". But mostly it just looks links to random extensions and applications. Why is there a link to VisualEditor, for instance? Is there really a desire for newbie developers to contribute to VisualEditor specifically? In most of the cases, the sections about these extensions/utilities don't even talk about developing them, they just talk about using them.
Finally, In the section "Add, manage and improve your content and structured data on Wikimedia sites", there's a link to Wikibase that seems out of place. It's titled "Store, manage and access structured data with Wikibase", which sounds unrelated to Wikimedia sites - and also makes it seem like Wikibase is the only way to manage structured data within one's own wiki, which is far from true. Yaron Koren (talk) 13:59, 7 May 2021 (UTC)[reply]
Hey Yaron Koren, did you see this HTML page? It has the content rendered per section, which may make it a bit easier to digest? It was linked from the content draft, but I added it to this page too now. -JHernandez (WMF) (talk) 16:26, 7 May 2021 (UTC)[reply]
No, I didn't see that before. Having tabs for each section is definitely better, yes. Yaron Koren (talk) 17:26, 7 May 2021 (UTC)[reply]
We removed VisualEditor and moved Wikibase to the "Enhance the MediaWiki software platform" section. --AKlapper (WMF) (talk) 21:47, 30 June 2021 (UTC)[reply]
VisualEditor was just the example I gave; it's not clear why there are links to any specific extensions or tools in the "Contribute" section. Why is Kiwix there, or Huggle? Or, now, Wikibase, for that matter? I think these should all be removed - unless any of these are specifically well-suited for beginning developers. Yaron Koren (talk) 15:32, 1 July 2021 (UTC)[reply]

Content: Do you miss any important areas or important links (which ones)?[edit]

  • Add your comment
  • A few areas with possible gaps:
    • Under "Enhance reader and editor functionality via on-wiki code", there should probably be a link for vega/graph-based data visualizations, and maybe for templatestyles CSS.
    • Under "Get metrics and statistics about Wikimedia sites for research and decision-making", maybe Wikistats? Unsure if that would be too off-topic, but I could picture someone looking on that section for that kind of data presentation.
    • The Wikidata query service should probably be somewhere.
    • "Contribute to the MediaWiki software platform and stand-alone applications" needs work.
      • Several major components are listed, but maybe it should also link to a more thorough list of all the parts in use, sorted/organized appropriately. There are quite a lot of things that are lumped into the Developer Hub, that people wouldn't immediately think to look there for. (More than is listed in the summary.) Not sure what should be done about this, but with the current structure, a lot of its content will likely be hard to find for users using the portal as a first step. Maybe something should subtly indicate "If you don't see what you're looking for in this section, check the Hub"?
      • "Desktop apps to save experienced Wikimedia editors' time" could use a directory link.
    • More generally: If I want to read about categories, or subpages, or how a certain strange bit of syntax works, where do I go?
    • A glossary somewhere would be good.
    • Maybe a link to something about the WM orgs' teams and what they're currently working on.
    • Some people are definitely going to arrive at this page thinking "but I just want to file a bug!", and get frustrated. It's not really what the page is for, but there should still be a link to Phabricator or How to report a bug somewhere.
  • Overall, this is very well done. Congrats to all who worked on it. --Yair rand (talk) 22:07, 6 May 2021 (UTC)[reply]
    • @Yair rand: Thanks! We added an item for TemplateStyles and to Wikidata query service. A link to Wikistats is available from the "Statistics about data and activity on Wikimedia sites" item which links to https://analytics.wikimedia.org/. Regarding "Desktop apps missing a directory link, indeed that is one of the several items to create on-wiki overview pages for, see phab:T278941. For reading about categories, or subpages, we have Manual:Glossary which could be linked from the Developer hub page as this is MediaWiki core territory. At this stage we don't directly link it from the developer portal though. We cover WM orgs' teams under "Find code base maintainers and stewards" (which could be expanded). For "but I just want to file a bug!" we rephrased the existing Phabricator item to also mention reporting software bugs. Thanks again! --AKlapper (WMF) (talk) 21:54, 30 June 2021 (UTC)[reply]
  • The page does not mention translation at all. Translation can be very useful entry point for new developers to get understanding of the software before they start contributing patches (that's how I got started). L10n and i18n are briefly mentioned at the bottom of the page, which does not match our values and priorities: MediaWiki is one of the most translated software in the world, we have i18n libraries in GitHub, translatewiki.net, etc. Would be nice to have a link how to get project set up at translatewiki.net, e.g. https://translatewiki.net/wiki/Translating:New_project and https://translatewiki.net/wiki/Translating:Localisation_for_developers may be less MW-specific general introduction to the topic. Nikerabbit (talk) 09:00, 11 May 2021 (UTC)[reply]
    • +1, we also know from academic research that i18n is one of the strongest predictors of the success of a software project (I can look up the reference if needed; it might have been in Schweik and English). Nemo 09:07, 11 May 2021 (UTC)[reply]
      • Translation is both covered by the listed Developer hub page ("Key documents, resources and tools for MediaWiki developers") and the explicit link to Localisation. That page's wording implies that the page is MediaWiki specific ("This page gives a technical description of MediaWiki's internationalisation and localisation (i18n and L10n) system"). If this is not correct (and its scope is broader) and the page should be more prominently listed, which implementation apart from MediaWiki core/extensions does the page cover? Localization is one area of software development, similar to performance, secure code, architecture, etc. If someone was a new MediaWiki developer, I'd expect them to go to "Learn how to develop MediaWiki code" linking to How to become a MediaWiki hacker which could mention localization. --AKlapper (WMF) (talk) 21:55, 30 June 2021 (UTC)[reply]

Content: Is there anything unclear or that could be improved?[edit]

  • I don't see an "edit" button or link, will there be one? Nemo 09:15, 11 May 2021 (UTC)[reply]
  • The tabs are confusing. In the tabbed version I have a hard time thinking people would be able to guess in which tab they will find what they're looking for. Instead of having to click 8 tabs and check each of them individually, a less strenuous option would be a page where all the things are listed together, or at least an overall TOC. For instance, I could never have guessed that "analytics.wikimedia.org" was going to be under "Get statistics for research and decisions" rather than "Use our content" or "Tools for your community". Nemo 09:15, 11 May 2021 (UTC)[reply]
    • @Nemo bis: Both the tabbed/HTML and the single/wiki version were meant to allow reviewing the proposed initial content; the implementation may differ when it comes to layout. I would not expect most people to think of analytics and statistics in the same category as using on-wiki content. "Tools" is explicitly about building tools (which also covers accessing replica data etc). --AKlapper (WMF) (talk) 21:56, 30 June 2021 (UTC)[reply]
  • I have no idea what "our" vs. "your" means here. If I'm a museum or an archive, I'm probably not uploading "my" works, but someone else's (usually in the public domain). Nemo 09:15, 11 May 2021 (UTC)[reply]
    • @Nemo bis: In the GLAM section this was an attempt to express that it is not about working with data that had already been uploaded by someone else. It's rephrased to "the content of your gallery..." now which hopefully makes it clearer. In the introduction and the newcomers section, "our" is intentionally used as Wikimedia hosts this portal. Thanks again for all your feedback! --AKlapper (WMF) (talk) 21:58, 30 June 2021 (UTC)[reply]
  • Add your comment

What do you like or dislike about this content draft?[edit]

ℹ You could use Positive / Neutral Neutral / Oppose Negative to prefix your comment.

Any other comments, thoughts, or feedback you would like to share?[edit]

  • Add your comment
Retrieved from "https://www.mediawiki.org/w/index.php?title=Developer_Advocacy/Developer_Portal/Content_Draft/Feedback&oldid=4679851"