Decision: Example documentation source-of-truth and maintenance (repo vs webpage)
Closed, ResolvedPublic
Actions

Assigned To

Authored By

	lojo_wmde
	May 21 2024, 7:06 AM

Description

Situation summary:

We currently have documentation on how to use the Wikibase Suite example configuration in both example/README.md in build pipeline repo as well also on the "Docker install page" on mediawiki.org. The content of both is and likely should be similar if not the same.

What is in our repository will naturally be updated along with related changes in the example. In support of agility, and ultimately clarity for our users, we should have a clear plan about how to keep the MediaWiki page up to date with what is in the repository.

Acceptance criteria:

We have a clear and agreed upon plan about the location of the "source of truth" of our example documentation.

If the MediaWiki webpage documentation for the Docker install is to mirror the example README, which is for now presumed, then we have a plan (including the related work plan or Phab tickets) of how to keep them in sync either through manual or automated means.

Related Objects
Search...

Status	Assigned	Task
Resolved	roti_WMDE	T365427 Decision: Example documentation source-of-truth and maintenance (repo vs webpage)
Open	danshick-wmde	T343354 Improve Wikibase Suite Docker install page
Resolved	roti_WMDE	T343359 Document how to reset a broken Docker install (e.g. docker compose down --volumes)

Event Timeline

lojo_wmde created this task.May 21 2024, 7:06 AM

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMay 21 2024, 7:06 AM

lojo_wmde renamed this task from Team Decision: Example documentation in the repo vs Docker install page to Decision: Example documentation in the repo vs Docker install page.May 21 2024, 7:08 AM

lojo_wmde renamed this task from Decision: Example documentation in the repo vs Docker install page to Decision: Source and maintenance of Example documentation (repo vs webpage).

lojo_wmde renamed this task from Decision: Source and maintenance of Example documentation (repo vs webpage) to Decision: Example documentation source-of-truth and maintenance (repo vs webpage).

lojo_wmde moved this task from Sprint-∞ to Prioritised + Unrefined on the Wikibase Suite Team board.

lojo_wmde edited projects, added Wikibase Suite Team, wbSuite Release Pipeline; removed Wikibase Suite Team (Sprint-∞).

lojo_wmde added a project: Documentation.May 21 2024, 7:20 AM

lojo_wmde moved this task from Prioritised + Unrefined to Prioritised + Refined (ready to be moved into the sprint) on the Wikibase Suite Team board.

lojo_wmde added a subtask: T343354: Improve Wikibase Suite Docker install page.May 21 2024, 7:23 AM

lojo_wmde moved this task from Prioritised + Refined (ready to be moved into the sprint) to Sprint-∞ on the Wikibase Suite Team board.May 21 2024, 7:34 AM

lojo_wmde edited projects, added Wikibase Suite Team (Sprint-∞); removed Wikibase Suite Team.

roti_WMDE claimed this task.Thu, Jun 6, 8:54 AM

Discussed in https://docs.google.com/document/d/1BbBHsjTrGwRAO_7v6hrXWdcd2q4jWo87-1xTJmFRgeA/edit#heading=h.d674s8t4i2am and https://docs.google.com/document/d/1BbBHsjTrGwRAO_7v6hrXWdcd2q4jWo87-1xTJmFRgeA/edit#heading=h.sdfekgm12jkx

Solution for now:

repo is the single source of truth
repo is the place to edit, maintain and review documentation
docker hub pages link to github repo build/*/ readme
mediawiki suite install page links to github repo deploy readme

This way docs cannot go out of sync, we have a single source of truth, the documentation processes are close to our dev processes.

Putting documentation automatically on docker hub and using MediaWiki for the "deploy docs" provides several benefits and will probably considered in the future again. It is considered out of scope for now through.

roti_WMDE closed this task as Resolved.Thu, Jun 6, 8:59 AM

roti_WMDE moved this task from To do (prio from top to bottom) to Done on the Wikibase Suite Team (Sprint-∞) board.

roti_WMDE mentioned this in T343354: Improve Wikibase Suite Docker install page.Thu, Jun 6, 9:02 AM

roti_WMDE mentioned this in T365195: Update Docker image user documentation.

roti_WMDE mentioned this in T365430: Decision: Docker image README location and relationship to Dockerhub page for image.

roti_WMDE moved this task from Sprint-∞ to Archive (closed) on the Wikibase Suite Team board.Tue, Jun 11, 2:13 PM

roti_WMDE edited projects, added Wikibase Suite Team; removed Wikibase Suite Team (Sprint-∞).