Page MenuHomePhabricator

Discovery of README documentation is poor
Open, Stalled, NormalPublic

Description

Discovery of existing documentation is poor, especially the documentation you would expect to find in README's. For example, the documentation for Wikibase Docker is in README-compose.md, not README.md . So when a user has a problem, they don't know which README's to read.

Event Timeline

Abit created this task.Sep 20 2018, 8:36 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptSep 20 2018, 8:36 PM

For example, the documentation for Wikibase Docker is in README-compose.md, not README.md

The documentation for the wikibase docker image is techncially https://github.com/wmde/wikibase-docker/blob/master/wikibase/README.md
Wikibase and other components should have their own documentation and the docker images should only care about documenting the extra stuff that they provide.

For Wikibase we have https://www.mediawiki.org/wiki/Extension:Wikibase which links to an install guide
The query service has https://www.mediawiki.org/wiki/Wikidata_query_service/User_Manual

I think all of this just needs to be tired together in a better way, perhaps wikiba.se website ?

Really we want to kill README-compose.md in its current form and also the example docker-compose file.
We probably want to lean toward the wikibase docker-compose generator for this, and pull all of this together with T205605.

Restricted Application added a project: Wikidata. · View Herald TranscriptNov 5 2018, 12:57 AM
Addshore changed the task status from Open to Stalled.Nov 5 2018, 12:21 PM
Addshore moved this task from incoming to needs discussion or investigation on the Wikidata board.
Addshore triaged this task as Normal priority.Nov 12 2018, 6:03 PM

Really we want to kill README-compose.md in its current form and also the example docker-compose file.
We probably want to lean toward the wikibase docker-compose generator for this, and pull all of this together with T205605.

I think the docker-compose generator sounds pretty cool, but please don't remove a basic docker-compose example from the repository. It's good to have a known-working example included - even if it's very basic - just so people can easily get to at least an "hello world" stage of a wikibase install. I didn't know anything about wikibase but I knew how to do 'git checkout' and 'docker-compose up' like any other piece of software. If I have to go to another site to generate the docker-compose file I'm not going to know what to select for any choices anyway, nor be sure that what I created actually works, and I won't be able to easily tell anyone what I've got.

Maybe there's a bit more cleanup to be done in the base README.md, but I didn't have much trouble finding README-compose.md