Page MenuHomePhabricator

Create a wiki documentation page for each tool
Closed, ResolvedPublic

Description

Not only is up to the owner of each tool at Wikimedia Tool Labs to provide documentation, but it's up to the owner to find a way to host that documentation. As such it's usually lacking, embedded in a source code repository, or shown as a static, uneditable page. There's no simple or standard way to provide editable documentation to a project.

Why doesn't every tool simply get a basic wiki page in a standard place which can be updated by the community? It can link to documentation elsewhere or have subpages with detailed docs, but either way there should be a basic documentation starting point that every tool should have.

I've create a rough example for "glamtools" to make the concept more concrete:

https://wikitech.wikimedia.org/wiki/Tool:glamtools

I propose we automatically create similar pages for all tools, so that we're not permanently stuck with only the simple creator-provided descriptions listed at tools.wmflabs.org. While there might not be a huge rush to help document existing projects, there should be fewer barriers for those who wish to help.

Why doesn't each tool already have a wiki page?

User:Pengo
Peter Halasz

Consensus vote

{V7}

Resolution

  • Create a "Tool" namespace on wikitech for documentation and discussion of Tool projects

Event Timeline

Pengo created this task.Jan 5 2016, 1:27 AM
Pengo raised the priority of this task from to Needs Triage.
Pengo updated the task description. (Show Details)
Pengo added a project: Cloud-Services.
Pengo added a subscriber: Pengo.
Restricted Application added subscribers: StudiesWorld, Aklapper. · View Herald TranscriptJan 5 2016, 1:27 AM
Pengo set Security to None.

The wiki would be a good means for collaboration, but I foresee many pages becoming out of date. Tool maintainers probably prefer to keep documentation right next to their code.

scfc added a subscriber: scfc.Jan 5 2016, 11:44 AM

We have such a place with https://wikitech.wikimedia.org/wiki/Nova_Resource:Tools/Tools and subpages, but it is not used very much. But, it's a wiki, etc.

I am very much against creating such pages automatically. If a tool's maintainer creates it and updates it, perfect. But there should no be another burden on developers' backs just when they create a tool.

As there is no "Tool:" namespace on wikitech.wikimedia.org, I have moved your example page to https://wikitech.wikimedia.org/wiki/Nova_Resource:Tools/Tools/glamtools.

scfc edited projects, added Toolforge; removed Cloud-Services.Jan 5 2016, 11:48 AM
Restricted Application added a project: Cloud-Services. · View Herald TranscriptJan 5 2016, 11:48 AM
Pengo added a comment.Jan 6 2016, 2:33 AM

another burden on developers' backs just when they create a tool

The initial page could be generated or copy-and-paste, and should contain very basic information (the name of the tool and maintainer, etc). Rather than be a burden, it removes the burden of having to find somewhere to add documentation, and allows the dev to share the burden of documentation.

Whether it's created automatically or not, it should be listed as the place to add a wiki page in the tool dev help pages, and the pages linked to from the tool directory. Otherwise it is useless.

scfc added a comment.Jan 6 2016, 10:15 AM

When a tool is created, only the tool's name and the name of the initial developer who created it is known. All subsequent changes (creating a toolinfo.json, adding other maintainers, etc.) would need to be redone on that wiki page as well, or users searching for the tool will find several pages claiming to be authoritative and having to figure out which one is current and which ones are bit rot. Even worse, developers might be unaware of the existence of the wiki page and their associated duties. That's why I strongly prefer that developers only have to maintain stuff they themselves consciously created.

Regarding the reference in the help page, it itself is a wiki, so be bold. But I would like to stress that Toolforge accommodates a lot of different tools that come from and live in a lot of different ecospheres. If a developer prefers that their documentation is in a GitHub repository or the user page of their bot on its home wiki or …, then that's fine with me. It must float their boat.

Rather than be a burden, it removes the burden of having to find somewhere to add documentation

I'm not sure if that's really the case. Instead of having one location for the documentation (maybe hard to find), there are now two locations, one of which the developer might not even be aware of. This makes life more difficult for the developer, not easier.

Example of this: pywikibot documentation. There's the official documentation on mediawiki.org, there's books on wikibooks (outdated), there's tutorials on different language wikipedias (outdated), there's pages on several wikia wikis (outdated), there's botwiki (outdated), and there's the 'pywikibot wikia' which is also outdated.

Pengo added a comment.EditedJan 6 2016, 9:33 PM

Example of this: pywikibot documentation. There's the official documentation on mediawiki.org, there's books on wikibooks (outdated), there's tutorials on different language wikipedias (outdated), there's pages on several wikia wikis (outdated), there's botwiki (outdated), and there's the 'pywikibot wikia' which is also outdated.

And wouldn't it be nice if every tool on this server had a wiki page which listed links like what you've given there?

In T123429: Create a Tool namespace on wikitech for documentation of Tool Labs projects @bd808 wrote:

Create a "Tool" namespace on wikitech that can be used by Tool Labs projects for tool specific documentation. I see this as being used in a manner analogous to the "Extension" namespace on mediawiki.org which hosts manually curated pages (and sub pages) for specific Extensions. Tool Labs project maintainers could use the namespace to document anything they found important for a given tool including maintainer documentation and/or end user support documentation.

I don't think that we should be automatically creating any pages on wikitech for Tool Labs projects, but I do think that carving out a clear home for on-wiki documentation for Tools is a good idea. I have a few tools that I would use the space to document how to support the tool (update the code, restart things, troubleshoot).

Today any tool developer could make a page in the main namespace of wikitech or a subpage under their User page or a subpage under Nova_Resource:Tools but all three of those options have discoverability problems. Pages in the main namespace may conflict with content created for the WMF production documentation. Pages under the User namespace are not surfaced in search by default and promote personal rather than collective ownership of the tool. Pages in the Nova_Resource namespace are tied to the technical OpenStackManager infrastructure currently in use on wikitech which may be replaced in the future and are also proposed for exclusion from default search in T122993.

bd808 added a comment.Jan 28 2016, 7:33 PM

Any objection by the watchers here to my general proposal from T123429: Create a Tool namespace on wikitech for documentation of Tool Labs projects to make a nice place for such tool docs but not automatically create any pages based on tool account creation?

We do have https://wikitech.wikimedia.org/wiki/Nova_Resource:Tools/Tools and subpages as an option today but that means the Tool specific pages are tied to OpenStackManager project pages (Nova_Resource:Tools). Using the namespace would also be more inviting for anyone who wishes to document a tool that actually lives outside of the Tool Labs project proper whether that is in another Labs project or using some other hosting solution.

As a developer, I support creation of a namespace and oppose automatic creation of pages for the reasons stated above.

Change 268616 had a related patch set uploaded (by BryanDavis):
Add Tool namespace to wikitech

https://gerrit.wikimedia.org/r/268616

Restricted Application added subscribers: JEumerus, Matanya. · View Herald TranscriptFeb 5 2016, 4:17 AM
bd808 updated the task description. (Show Details)Feb 5 2016, 5:18 PM
greg added a subscriber: greg.Feb 5 2016, 5:19 PM

This comment from T123427: Create Portal namespace on wikitech to give a place for audience specific landing pages seems relevant here.

What would such a namespace accomplish? You can always name a page Portal:Something (or, if you prefer plain English, Something portal). It seems like there would be about half a dozen portals altogether, so the navigational benefits of a separate namespace do not apply.

That would depend on whether you are having a freeform namespace or looking to apply some method and rigour.
The Wikisources use their namespaces well to sort and coordinate their subject matter. They also apply templates that allow for a standardise look, feel and data in a ready fashion. Be that data be auto or manually generated is less relevant that the quality of the data. Giving guidance and standardised templates to handle the introductory aspects gives uniformity and the basis for better data, and the evolution of that data over time. The author namespace in English Wikisource has proven very successful for use, for addition of data, for tailoring searches; linking to wikidata, etc.
So I support a specific namespace addition be it portal:, or tools: though it will need more than the namespace, it needs its development of structure and attention to pertinent detail.
Also looking at the discussion above, I also believe that it has forgotten that our tools sitting in a namespace of their own also opens up an opportunity to be linked into Wikidata as the these tools become what is notable at Wikitech, with the best tools being the portent of components opening the Pandora's box to Wikimedia sites. Having a namespace also provides an ability to look at tools historically, both in their own development sense, and the antecedents and successors, active vs. closed. All good data to be added manually or to be pulled from Wikidata.
So I think that if we have an outward focusing consideration of Wikitech, rather than a myopia. There is a lot of scope for good data that gives wikitech and its projects their own notability.

My general thought on the Tool namespace is that it should be something similar to the Extension namespace on mediawiki.org (link is to Category:Extensions which serves as one entry point into the Extension:* content). Template:Extension and categories provide the main semi-structured and structured data that make the Extension pages a cohesive group. It would be great if people interested in the Tool namespace started to think about what a similar organization for Tool pages might look like and discuss it here.

The main difference I see between on-wiki documentation and something like Hay's Directory is that a wiki is a wiki. :) Collaborative editing and discussion are powerful tools for improving documentation and solving shared problems. Having an easy way for Tool developers to "register" their tools with a search tool is a great feature, but it doesn't allow Tool users to collaborate on documentation or give an obvious place to ask and answer questions. For some Tools there are better places to advertise and organize discussion (e.g. a tool designed mostly to solve problem X for on-wiki community Y should probably find a home for the documentation in that wiki), but I think that Wikitech can be a "home" for Tools that have no other obvious place in the projects.

I supported the poll since I agree with adding the namespaces, but don't think it sets a good precedent of using numerical polling without comments to figure out how a wiki should be organized, or standard configuration changes.

bd808 added a comment.Feb 19 2016, 8:37 PM

Poll results:

  • Support: 23
  • Oppose: 1
  • Neutral: 5
bd808 updated the task description. (Show Details)Feb 19 2016, 8:41 PM
bd808 added a comment.Feb 19 2016, 8:46 PM

I supported the poll since I agree with adding the namespaces, but don't think it sets a good precedent of using numerical polling without comments to figure out how a wiki should be organized, or standard configuration changes.

I'd love to see wikitech treated as a "real" wiki. To my knowledge there really isn't much policy and procedure around how it functions. As I said in my email to labs-l this was an experiment. The poll and this task did offer space for comment, but twiddling thumbs for 2 weeks for a fairly trivial config change may not be the best way to move things forward.

Change 268616 merged by jenkins-bot:
Add Tool namespace to wikitech

https://gerrit.wikimedia.org/r/268616

bd808 updated the task description. (Show Details)Feb 23 2016, 2:05 AM
bd808 closed this task as Resolved.Feb 23 2016, 2:08 AM

The Tool namespace is live on wikitech. I have also moved the tool documentation pages that were hosted under https://wikitech.wikimedia.org/wiki/Nova_Resource:Tools/Tools to the new namespace. I did not move https://wikitech.wikimedia.org/wiki/Nova_Resource:Tools/Tools/Pywikibot.