[docs] Global wiki 'Site Notice' needed

Destry · 2015-11-26 12:36:42

As I read through this thread about ‘image forms’ and observed the frustrations expressed there, a couple of things occurred to me. One, for purposes here, is that the old wiki is more problematic at this point that helpful, and the sooner people are clued to look at the new documentation location, the better.

This can be done easily using the site notice feature, but it needs a wiki administrator to do it (I’m not one). Create a site notice message that says something like this:

This wiki is now locked to further changes, including corrections to documentation. See the new Textpattern user documentation site for updated docs. If a new page is not there yet, it’s still work-in-progress and the associated wiki page here is still the only reference. When the new documentation site is finished, this wiki will disappear and all links will be redirected to the new docs homepage.

Leave that up permanently until the wiki is taken down entirely.

Waiting until everything is done at the new docs location before redirecting people and linking there is a mistake. The sooner they’re conditioned to look there, the better. After all, it is now the only location where documentation is edited.

The more people keep talking about the old wiki and making links to it, the more detritus generated unnecessarily. Leave the wiki up until the new docs are completely done, but at least put in the global notification message so the world understands what’s going on and might actually find more helpful information.

I should add that while I’m still dedicated to editing the new docs, I am busy with greater priorities at the moment so my pace has slowed considerably by necessity. The help of another GitHub-using writer/editor would be appreciated, I’m sure. We did have a volunteer, but I can’t remember his name now.

Last edited by Destry (2015-11-26 12:47:51)

philwareham · 2015-11-26 13:32:55

I don’t seem to be a wiki admin myself. I will contact Robert to see if I can get access.

mistersugar · 2015-11-26 17:24:06

Destry wrote #296823:

… the new documentation location

Aha, that’s the first I’ve heard of new documentation, and I’m a daily visitor to this forum, and I’ve been on the txp tags documentation much over the last month. So, yes, please point us to the most relevant documentation.

I’ve got a few other of my forum threads to respond to (now that I’ve relaunched my Zuiker Chronicles) to thank the community for helping me learn about this CMS that I’ve been using, happily, for more than 10 years.

philwareham · 2015-11-26 21:14:57

Robert has given me some pointers on how to amend the wiki – I’m hoping to do that tomorrow.

Destry · 2016-07-04 07:20:28

BUMP!

We’ve been seeing a lot of new community users and adopters of Textpattern. Yay!

It’s more important than ever now to stop promoting the deprecated wiki and start pointing to the new Textpattern user documentation, and to the new maintained Tags reference in relation.

To the lords of the global navigation, I’ve suggested it before, but it would be nice if the “Documentation” link in the global navigation was corrected and a site-wide notice was put in the wiki to inform visitors their of the new location.

It doesn’t matter that the new docs are not finished. (If we always waited on the ‘finished’ state of something we’d never get anywhere.) Better to start encouraging the right place. If this results in more questions in the boards about missing docs, then we know where the deer tread most often and can prioritize doc-writing efforts — a win win.

colak · 2016-07-04 08:31:10

Hi Destry,

You are indeed right. Someone with ftp access will need to change the “Documentation” link in this forum to the new one. I’m willing to change the links on the .com, .net .org etc sites if I am given access.

Destry · 2016-07-10 13:13:55

BUMP!!!!!

Destry · 2016-08-08 10:05:53

philwareham wrote in the 4.6 beta2 thread #300537:

The [docs] site still needs quite a bit of work though before it’s officially launched.

I don’t understand this logic of waiting until everything is done. That’s not how you write documentation. You make what you have available, put it out there, and let it start helping people. And you correct links to documentation so that supported docs are the ones people are being directed to and properly bookmarking. Txp track record for getting things done has shown that if we wait for the big finish, it could take another several months or more (years is usually the scale).

The new docs site, while not finished, has a lot of updated and useful information. But navigation, this forum, etc keeps pointing to the deprecated wiki, which is as useful as a bottomless bucket. Even veterans don’t know the new docs site exists and where attention should go. That’s why you keep seeing people like Dale point to the wiki Tag Reference.

My email address is on the wiki admin, still, apparently. I get routine emails from people asking for wiki accounts and whether this page or that is still relevant. Every time I have to explain the wiki is deprecated and point them to the new location. For example, one person wanted a wiki account to add a developer prefix. Well, that new info, and the process for establishing a prefix, is already written in new docs because I identified early that the new dev docs would be a priority rewrite. Had we had the proper cues in place in the wiki this thread has requested several times, that might have been one unnecessary support call. And that’s the whole point of documentation. Self-sufficiency!

And if people can’t find what they want in new docs, they’re instructed to ask in these forums, as usual, which in turn informs us few docs writers about the doc pages needing the most priority. That’s how it should be. This can all be working for us now.

No offense, Phil, I know you do a lot of work, but this all-or-nothing approach to Textpattern websites is kind of a setback. They should not be big waterfall exercises for which the launch dates get pushed back indefinitely because there’s “quite a bit of work”, or because the scope keeps creeping. How long until .com is redone? That’s been mentioned a few years now. Or fixes to TXP Mag? A complete blocker to publishing articles, even if anyone wanted to step up as an editor. Those sites need changes, lots of them. But at the time it only ever needed to be little changes — evolutions to this and that — to make them functionally useful and better. And that’s how websites should be: rolling, adjusting to need.

But let me stay focused here:

Change all “documentation” homepage links to the new docs location.
Put in the site-wide redirect statement in wiki pages so people know what’s going on and where to look.
Swap my email address in the wiki with your own, wherever it’s using me as admin.
Steer them to the forum to ask questions if necessary (via wiki statement and a site-wide statement in new docs).

That’s how you get this documentation project finished and working sooner.

philwareham · 2016-08-09 14:59:22

I’ll see if I can find some time to get the docs site swapped over and in a state where it is useable within the next couple of weeks. The forum also needs updating to the latest FluxBB version and some styling amends that tie it into the overarching style I’m using for the family of sites, so I’ll do that too.

All the Textile docs in the documentation site need rewriting as Markdown if anyone wants to volunteer for that task (I’ve done quite a few already but lots of pages still to rewrite).

Bloke · 2016-08-09 15:03:53

philwareham wrote #300568:

All the Textile docs in the documentation site need rewriting as Markdown if anyone wants to volunteer for that task

Hint for anyone who steps up. Download it. Works wonders.

michaelkpate · 2016-08-09 15:47:20

philwareham wrote #300568:

All the Textile docs in the documentation site need rewriting as Markdown if anyone wants to volunteer for that task (I’ve done quite a few already but lots of pages still to rewrite).

I’ll volunteer because I’ve been wanting an excuse to really dig into Markdown.

philwareham · 2016-08-09 15:56:43

Great! If you want direct write access to the documentation repo on GitHub then let me know your GitHub user name, or you can fork the repo and provide pull requests, whichever is easiest for you.

Then, basically, it’s a matter of taking a Textile document (anything with .textile file extension) and saving as .md with Markdown formatting. Note that of the many many flavours of Markdown around, GitHub’s hosted Jekyll uses Kramdown so please adhere to that formatting.

The tags documents I have already converted (mostly) so feel free to peruse those for formatting tips.

Textpattern CMS

Textpattern CMS support forum

#1 2015-11-26 12:36:42