Documentation content - What to do about the Wiki (Revisited)

I already posed this question almost 2 years ago, see issue: https://github.com/TYPO3-Documentation/T3DocTeam/issues/8

Since then some things have happened but not enough to sufficiently make headway.

What has happened:

  • I (and a few others) have been doing some cleaning up: Determine pages where the content has already moved elsewhere (mostly docs.typo3.org), remove these pages and request redirects. More than 50 pages were removed this way.
  • created lists for migrating content, see https://github.com/orgs/TYPO3-Documentation/projects/3
  • a Slack channel was set up: #typo3-wiki
  • several people got together and decided to create a Wiki2docs initiative. This never really took off.
  • it was communicated that it was decided to make the Wiki readonly. I don’t really know who decided this and why.

To help the workflow, I used the already existing tags and categories to mark the content, e.g. {{delete}} is candidate for removal, see https://wiki.typo3.org/WikiMigration

I think, in order to proceed, this topic needs a decision. And then people executing it.

The decision

Possible choices are:

  1. Take down entire Wiki. This has the difficulty that it is not just used for docs. It is also used for exceptions and some team communication, see https://wiki.typo3.org/OverviewOfWiki
  2. Merge, remove and redirect on a 1 page at a time basis: Remove pages that are outdated or where content is already moved elsewhere. For the rest, possibly move content to docs.typo3.org. Remove the page and create a redirect.
  3. Make Wiki readonly. This was suggested but I don’t really see the merit. Maybe someone else can explain.

You may think choice 2 is unrealistic but it is actually doable with a few more people pitching in. As a whole, we have about 1000 pages. 50 were already removed, 283 are exceptions, 147 are already candidate for deletion. Probably, these just need redirects and get removed. see https://wiki.typo3.org/OverviewOfWiki#Number_of_pages. A number of pages can just be removed with little effort. For others it requires more work.

My recommendation

This is a combination of 1 and 2 above in a multi-phase process.

  1. Have someone in charge of the process to coordinate this
  2. Continue with the migrating / deleting / redirecting on page-by-page basis
  3. Communicate ASAP that entire Wiki will be taken down in 1 1/2 years - Oct 8, 2021. Communicate how everyone can help and what needs to be done.
  4. Start looking for alternatives for exceptions and communication (e.g. t3board, various groups)

Sub-suggestion: communicate decision

In any case, I think it would be a good idea to communicate this decision on a broad basis, e.g. Wiki will be taken down in 1 1/2 years - Oct 8, 2021. Until then, we strongly urge everyone to pitch in, move content, remove content and create redirects.

Sub-suggestion: Archive Wiki, make available for download

I would propose to archive currrent Wiki right now and create a downloadable tarball. Ideally create a backup of current system and a “static copy” (e.g. with wget) for local viewing.

The reason: It is far more easy to remove things if there is at least a backup of the content somewhere. IMHO, some of the content is still useful. But still, it needs a more rigorous cleanup (than is currently being done). Otherwise we will be revisiting this topic again in 2 years. I don’t think it is a good idea to keep postponing this.

I have not tested the viability of the “static copy” for wiki.typo3.org but I have done this for other systems (often it needs a little tweaking). It is important to create an archive with relative links and paths to assets so you can view this locally, just using a browser.

Example:

# -k: convert links
# -m: mirror
# -nc: no clobber (do not overrwrite files with same name)
# -p: download necessary assets
# -E: append .html to HTML file if doesn't end in html
wget -E -p -nc -m -k https://wiki.typo3.org

Sybille, great iniciative and I agree with your point of view in all regards. I don’t want to “vote” on anything yet, just add another idea:

Gather input from the “most accessed wiki pages” and focus on them. We know people reach our wiki mostly from search engines. If we manage to update the destination of the say “top 20” accessed pages, that would already satisfy 95% of the needs, and make it easier to argue taking down the wiki.

1 Like

2020 Page Numbers:

I think we should add a dynamic redirect for /Exception/CMS/[number] to a new destination on docs. which will take care of a huge percentage of visits already.

@andri.steiner Thank you.

Ok, so besides the exceptions we have a lot of hits on these, see issue:

This quite nicely illustrates the problem. Some pages are pretty easy to just redirect and remove because the information is outdated on the wiki page and / or already exists elsewhere.

For some, it is more difficult, because the information is still at least partly relevant and there is no real alternative. This does not make it impossible though, it just takes a little more time to look at existing content and make a decision if the outdatedness outweighs the usefulness.

Just in case you did not know:
The extension stuff in the Wiki was never meant as “documentation” but rather as a possibility for everyone to add information how/why an exception occurred and possible ways for mitigation.

I’m not sure if moving this to the docs really makes sense. Besides that I guess that this information is mostly more spread in Slack and StackOverflow, the latter one being the best choice presumably.

1 Like

No, moving this to the docs does not make sense (if it is not documentation). I rarely ever really move anything 1-1. I check if it exists already, sometimes just a small part is missing on docs.typo3.org, most of the time it is more a less a complete rewrite. The important thing (for me) is not to delete anything valuable unless there is a good replacement.

What I have seen so far in the Wiki related to extensions:

  • extension documentation in Wiki for older extensions. Yes, there was documentation for some very old extensions. See for example bananas or vimeovideo. There were lots of others, but we already added some redirects.
  • blueprints for new extensions or new features. This was sometimes a proposal, a specification or just an idea and a request for discussion.

I think, for what is currently still in the Wiki for extensions, we would nowadays often rather do as issues or pull requests in the GitHub (or gitlab or whatever) repo or as documentation.

I would keep the exception description stuff and the blueprints for the time being. (maybe an incomplete list of mine, but that’s what comes into my mind hearing “wiki”)