Wiki development

els · 2014-01-19 16:18:12

I don’t mean to criticise your efforts, Phil, but I think I need some reassurance here…

philwareham wrote #278277:

Basically, as part of the redesign of the brand sites I’m currently deciding whether to scrap the Textpattern.net wiki platform entirely and look at whether there’s a better way of hosting the collaborative documentation efforts. I’m thinking host the docs on GitHub and then pull them back to a Textpattern installation on the textpattern.net domain somehow. To this end, I’m extracting the (viable) wiki docs and rewriting them on GitHub as Textile documents (they may one day become Markdown documents depending on how we decide to serve up these pages).

I’m also taking this opportunity to improve some of the info – but that is a long-term thing which hopefully I’ll get other people helping me on. There’s a lot of out-of-date docs on the wiki.

Just a few questions that come to my mind. Will this influence the readiness to contribute to the documentation? Isn’t GitHub a much higher threshold than a Mediawiki installation? And if the documentation is maintained in GitHub, does that mean that changes won’t be immediately visible to the public?

philwareham · 2014-01-19 17:41:18

I’m not saying there won’t be the wiki as yet, I just haven’t investigated all options. The wiki can use Textile so I may transfer the docs back. MediaWiki is hard to style up and customise so I’m not too keen on it from a design and structural perspective. I could do much better SEO on it and make use of content schemas without it.

It was a good servant, but things move on so I’m keen to see what alternatives we have nowadays.

There’s a handful of active wiki contributors. Most of the accounts stand idle and unused, so it probably wouldn’t make a huge difference to contributions. It may be better, it may be worse.

And yes, the changes wouldn’t be immediately visible to public – they’d be peer reviewed as GitHub pull requests (although MediaWiki can also do this, I’ve been informed).

The other advantages I can see of not using the wiki and using GitHub (at least initially) are:

you can use whichever text editor you want, not forced to use the inbuilt wiki editor.
the doc pages can be utilised for other uses, such as authoring a book. The export tools from the wiki are almost non-existent.
the files are just that: files. You can edit them offline and have all data available at a quick glance (there are a lot of obsolete pages buried in the wiki which are difficult to track down).
I could convert it fairly quickly from Textile to Markdown if we find a tool perfectly suited to our needs that doesn’t support Textile.
We can use Textpattern to host it (maybe) – we are meant to be a content management system after all, if we can’t comfortably host our own documentation on our own CMS then we might as well just give up.

gaekwad · 2014-01-19 20:30:45

philwareham wrote #278285:

We can use Textpattern to host it (maybe) – we are meant to be a content management system after all, if we can’t comfortably host our own documentation on our own CMS then we might as well just give up.

Yeah, this ^^.

I appreciate there’s a crapload of work involved with documentation, regardless of what infrastructure is used. The fact that 4 people have edited the wiki in the last 30 days, three of whom are now participating in this thread (and I expect Uli will be along shortly), implies that there’s a barrier to entry and participation on the wiki side of things anyway. Yes, anyone with a forum account can have a wiki account, but there doesn’t seem to be a influx of authors and editors.

I’ll level with you: I think it should be on Textpattern. I think it should be given the Wareham + Svahn Website Shopfitters SWAT Team overhaul and interested parties should be encouraged to become authors. Here’s why:

Mediawiki is not the most user-friendly thing to learn and use. I say this as a Mediawiki Kludger without any vested interest.
There are people here who make Textpattern CMS. Let’s make and manage some content.
It’d be an excellent opportunity for it to be multi-user with levels of control. More people using it, more eyes on improving it; not that I’m saying it needs improvement, but enhancements might be shortlisted.
It’d be an excellent opportunity to have content authors start creating for TXP Mag and see if/how that can be rebooted. I haven’t seen Destry around here lately, and that’s a real shame. I’m a guilty party insofar as I said I’d do stuff to help, but real life got in the way and I’ve learned my lesson about committing to third parties.

I love the idea of a GitHub repo. I just about know what I’m doing around those parts, but I can see the logic behind it. I can’t see how a GitHub + Textpattern gluey solution would work with flat files and a database, but then I’m not that smart, so I’ll leave that to Oleg and etc_query as I am wont to do in these scenarios.

els · 2014-01-19 21:21:35

MediaWiki is hard to style up and customise so I’m not too keen on it from a design and structural perspective. I could do much better SEO on it and make use of content schemas without it.

OK, this and your #5 make sense to me :) A couple of new questions arise though.

Who will do the peer reviewing? If that’s going to be Jukka and you, it will only add to your workload, and is that what you want?
Along this line, does this mean the dev team will be the sole supervisor of the documentation? Of course Destry doesn’t have all the time in the world, but he has been doing a great job in structuring the wiki.
Wouldn’t a Textpattern installation (like the .org site) work?

Again, not trying to oppose, just thinking out loud ;)

philwareham · 2014-01-19 21:37:12

I think I can give write permissions to a group of users on GitHub, per repo, so it’s not out if the questions that there could be a number of peer reviewers with the rights to accept pull requests. I don’t really want to handle it myself past the initially setup and content restructuring.

I don’t know how the .org site works at the moment, I’m trying to avoid that one for now.

etc · 2014-01-20 09:50:51

gaekwad wrote #278299:

The fact that 4 people have edited the wiki in the last 30 days, three of whom are now participating in this thread (and I expect Uli will be along shortly), implies that there’s a barrier to entry and participation on the wiki side of things anyway.

Unfortunately, not all of us master the Shakespeare’s language, gentle sir.

Destry · 2014-01-20 10:12:39

Phil and I have been communicating about the wiki via email. I was approached kind of after-the-fact, but talking we have been. Aside from that, I do keep my thumb on the pulse of community activity even if I don’t spend a lot of time in these sexy boards anymore. (I still have the problem of forum notifications not working for me, so that impacts my desire for this channel).

Second, I think the wiki is not the next family site to be worrying about if all we’re talking about is site branding. Sure, the docs need cleaned up, but the wiki isn’t holding that up. Lazy writers are what’s holding that up. On the other hand, if Txp is trying to create a more refined docs handling process that includes UI help too, then that’s at least an argument for doing something in the direction of code. Does that need to include Phil, when Robert, Steph, and Jukka are already coders? I don’t see why it should. To my mind, .com is where Phil needs to be putting his energy at the moment. Then the magazine, which is partly in limbo because it needs front-end changes that are at the mercy of Phil’s agenda. (Not to mention a lack of article contributions from the community.) Only when those two sites are back on track should anyone be worrying about the docs site, which works just fine in the meantime. Yes, writing is hard, and it’s not the tool’s fault that it doesn’t get done.

Third, back to the wiki… A wiki is far superior to Textpattern in terms of collaborative writing. I won’t even waste time trying to prove that statement. But, after spearheading the wiki into existence back in 2004, and watching this community’s dynamic with it — altogether one big interesting experiment — I’ll be the first to say that the wiki’s time is over. Not because of crap reasons like it’s too hard to use, but because this community just doesn’t contribute much to documentation. Never has. The wiki was chosen for two reasons and two reasons only: community collaboration and docs translation. After ten years, neither has proven to be very impressive, speaking overall. The translation efforts, especially, have mostly been an uncoordinated mess, resulting in lots of outdated/abandoned pages clogging up the internet.

Fact is, it would be very good for Txp docs if the process moved to one where docs were managed by a smaller dedicated group of editors in English only. Doing this means the wiki is overkill as a tool, and just about anything else is viable so long as it’s web-based and provides secure access and version control features. IMO, Textpattern is not the only tool to consider. Github has potential, but even there it’s mostly a designer/developer’s tool. That was until Penflip came along. Will that serve the need? It’s really just a matter of opinion and choice of Team Texpattern. If they want to use Txp. I don’t care.

Fourth, while my role in the wiki has been undercut more and more as time goes by (and I’m not complaining because I don’t have a lot of time anyway), I have offered to keep giving help with writing/editing. So if there does end up being some limited editing team on docs, feel free to keep me mind for that. I would also suggest keeping in mind those top contributors who have made a difference with docs over the years.

philwareham wrote #278285:

we are meant to be a content management system after all, if we can’t comfortably host our own documentation on our own CMS then we might as well just give up.

“CMS” has always been a stretch for Textpattern (for the sake of search rankings). A web publishing system is more like it. Being able to use the acronym, API, would be a more distinguishing feature to boast. Alas.

gaekwad · 2014-01-20 10:27:15

etc wrote #278307:

Unfortunately, not all of us master the Shakespeare’s language, gentle sir.

You are correct. However, the beauty of collaborative editing is the peer review, so you don’t need to be a master. I’ve been speaking English for 35+ years, I still regularly get things wrong.

philwareham · 2014-01-20 11:05:34

The documentation site is kind of related to the .com site since there is currently cross-pollution of documentation (FAQs sit on .com and full documentation sites on .net) – this needs to be amalgamated. Well, the FAQs need to be audited and rewritten where appropriate on the .net site, and removed from .com.

Also, if there is the decision to use Textpattern to power the documentation, most of the codebase/style of .com can be used for .net without any major rewriting (maybe just a few extra page/form templates). That makes ongoing maintenance easy and manageable.

So I’m developing both sites in tandem (or rather, I’m building .com but always with an eye on how it will power .net).

Same goes for .org, although that set needs some major thought and coding. They all will use a subset of the design patterns I’m building.

The TXP Magazine site also has some some shared codebase (yes, I have worked on it intermittently).

federico_ru · 2014-01-20 11:16:52

BTW Phil, I love what you’ve done around here, too.

gaekwad · 2014-01-20 11:17:55

federico_ru wrote #278314:

[…] Your pompous and smug attitude is more suited to drupal than here, so take the hint and gtfo.

Ha! That made me laugh. You could block my replies, I guess – maybe that would work for you.

GugUser · 2014-01-20 11:51:02

Please, can an admin delete federico_rus post? We do not need insults in this forum.

Textpattern CMS

Textpattern CMS support forum

#1 2014-01-19 16:18:12