User:Thepwnco/Documentation Overhaul/Summary and Feedback

Context of Documentation Overhaul

As part of my internship and work for improving outreach efforts for Wikidata, I've been reviewing some of our existing documentation in terms of what we're getting right and what we could be doing better (especially when it comes to supporting new contributors).

The pages I've reviewed so far mostly consist of those in the Category:Help-en.

I think our documentation is overall very strong but it is not as beginner-friendly as it could be, likely owing to the very technical nature of Wikidata (especially when compared to other WMF projects), and, because it was perhaps more geared towards developers than editors from the start, it tends to assume a baseline familiarity with structured data as well as wikis that new contributors might not have.

Areas of Improvement

I think a few things could be done that would go a long way in making Wikidata easier to understand. Here are the main areas of improvement to documentation that I am proposing:

• documentation needs better integration between Wikidata concepts and existing site examples/screenshots

For instance, sometimes examples of concepts will be at the bottom of the page rather than immediately after the explanations or step-by-step instructions on their usage; other times the user needs to go to a different page or click through a slideshow tutorial to find what it is they're looking for

• documentation needs to be updated! You guys have accomplished so much in such a short time and implemented a lot of new things which is great but it also means some of the notes on functionality and screenshots are no longer relevant. I'm betting our FAQ page could also benefit from what all you seasoned contributors now know - and what you wish you had known when you first started out
• documentation needs to be modified so it has less of a focus on just Wikipedia and instead caters to users from other WMF sites as well as users with no previous experience with wikis
• documentation needs to be more reader-friendly and scannable
• documentation needs to provide a better bridge between straight-up information and engagement

Next Steps

To accomplish the above, here are the main actions that I am proposing:

• develop a page for wiki newbies - this could be as simple as a page that aggregates a bunch of existing Mediawiki/WMF links with information on formatting/editing pages, using talk pages, understanding namespaces. The last part is key: IMHO, we need to include a bit more information on basic site structure (not data structure - although I'm sure that could always be improved too)
• create a more standard structure for similar Help pages. For example, all the pages on editing items could include common sections on guidelines, usage, examples, and exceptions. I think all pages should also include enough basic/introductory information on a given concept (e.g. sources, qualifiers, etc) instead of assuming a user has already read through the glossary or other relevant pages
• clean up pages by removing redundant content (I have already started the messy process of an information audit here). I think it'd also be nice to, if not resolve, at least push for some decisions on the Help pages with a {{Proposed}} notice for becoming a policy or a guideline (for example, see here)
• post on project chat on what to include in the new FAQ. I'd love your suggestions
• revamp documentation so it is more action-oriented. By way of example, see the Help portals for Wikipedia and Wikivoyage, which are both organized in a way to help support a user accomplish a certain task; for this reason I am considering merging our Contribute and Help portals together. I'd also like to expand some of the content for different pathways of contributing, such as aggregating all dev related stuff together and putting together some basic info on starting/being part of a task force

These are just some initial thoughts but I wanted to hear what you're thinking and if my proposed next steps are worth pursuing. Please leave any feedback you have here. If you have other comments related to what you feel are the strengths and weaknesses of our documentation, please also let me know. Thanks Thepwnco (talk) 22:35, 16 June 2014 (UTC)

Feedback

• I think we should have a section help in the Community portal with all links to help pages. I think we created to many pages and we need a centralized page with all subjects concerning wikidata. Something like the french community portal french community portal. Snipre (talk) 10:10, 17 June 2014 (UTC)

  For me the Contribute page is useless because it is just an additional layer between the main page and the important pages containing information. We have to simplify between main page, community portal and pages like contribute page to have someting more condensed.Snipre (talk) 10:15, 17 June 2014 (UTC)

• I would like to point out that given the multilingual nature of the project, it is better to modify the help pages in batches, that way the translators have a solid version to work on. It would be good to have more screenshots pointing out to the interface, but since that is going to change soonish I wouldn't start it now. What in my opinion is missing:

1. Dictionary humanish-wikidatanish, how to express natural language patterns of information as wikidata statements. Examples: "The planet Earth will eventually collapse and there is more info about it on the article 'Future of the Earth'", this translates as "Earth <date of dissolution> unknown value with qualifier <subject of> Future of the Earth". We are constantly developing new patterns, but we are not recording them anywhere, so users have no central place to share them, discuss them, or agree on them.
2. Community blog to showcase topic-oriented work (plus the weekly updates). Now we only have "showcase items" but that is not enough, new users need to know about how other editors approached multi-item projects, like "importing all WWII battles into Wikidata", or "electrical motors properly classified". We have tons of editors doing such amazing efforts, but they have no place where to share their stories, approaches and solutions.
3. Infobox properties, given an infobox, which properties are related to it? There is Wikidata:Infobox mappings, but this is not human readable. This could be thought as an improvement over "List of properties", to be automated when statements are allowed on property pages.
4. Bot library. Many bot operators are publishing their source code, with so much code a "bot library" of past bots could be created, classified by type (import, clean, move, delete, etc) and domain. That would lower the barrier for people wanting to operate a bot, just take one that was already used, adapt it to your data, and request permission.

--Micru (talk) 13:01, 17 June 2014 (UTC)

• An important step to support the benefits of a better documentation would be to prevent new users from turning away before actually getting to the documentation. This is most likely out of scope of the documentation overhaul, however, in that sense, overhauling the Main Page would be an important task. The Main Page is cluttered with links and is much too static to be inviting to new users. There is no demonstration of the purpose of Wikidata in any way. Random knowledge donator (talk) 09:15, 26 June 2014 (UTC)
• Another important aspect of improving documentation would be to overhaul the glossary in terms of consistency and more usage of common language. (However, this would probably involve having to change internal messages/string as well.) "Data set", "entry", "item", "page" for example are hard to distinguish unless your into the techniques. Terms like "qualifiers" are simply odd as the qualifiers do not qualify a statement's value. No one will grasp that term without reading the manual. Random knowledge donator (talk) 09:49, 26 June 2014 (UTC)
• I´d like to bring up some general wishes on the behalf of the translators. First of all the inconsistencies of the technical terms makes it much more difficult for the translators to find suitable translations. If the original version contains three different words for the same thing, the translator has to find three translations. He has to take care the translations do not mix up the reader with concepts he knows from elsewere and interfere the understanding the nature of the issue. Next thing is to keep everything as simple as possible. As I am a translator I can tell most other western languages are capable to handle long sentences full of subordinate clauses, but there are languages that are not. So please keep the barriers low. Stick to main clauses and keep sentences as easy as possible. We also have to deal with translators in some languages that have only basic languages skills. This also improves readability to all users. Next thing is to use multilanguage templates whenever possible. So please use {{Q|####}}, {{P|####}}, {{Ll|Help:Page}} instead of square brackets [[Example link]]. This helps users to find the pages in their languages and encourage them to translate it, if there is no version in the local language. Whenever there is an item that lacks label and description in a local language, its better to update the item instead of translating the description of the link. We throw away the special abilities of a multilingual environment by ignoring this, force the translators to translate the term multiple times and so produce unwanted inconsitencies, let alone the confusion when a property is renamed. The user also gets less stressed with navigating the pages by finding the local version immediately and is not distracted by serching his version every single click on a link over and over again. There also should be a WikiProject translations to secure that in every language there is a translation at least of the glossary and the predefined top twenty help and information pages.--Giftzwerg 88 (talk) 11:35, 6 August 2014 (UTC)