Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#13 2015-06-29 12:51:28

philwareham
Core designer
From: Haslemere, Surrey, UK
Registered: 2009-06-11
Posts: 3,564
Website GitHub Mastodon

Re: [docs] Github wiki

Please don’t rush into anything straight away – I thought we were going to use Jekyl via GitHub Pages for hosting this stuff, not the GitHub Wiki.

This was the kind of setup I was thinking of – we also use our own domain name and all the SEO benefit that comes with that (instead of being lost amongst the github.com domain name). If you want a setup of it

Offline

#14 2015-06-29 12:56:15

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: [docs] Github wiki

philwareham wrote #292251:

I thought we were going to use Jekyl via GitHub Pages for hosting this stuff, not the GitHub Wiki.

Whatever works. I’d forgotten about that actually, sorry. Good plan.

So what should we set up, and how, if people like Destry and Bert want to get involved with the documentation drive now?


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#15 2015-06-29 12:57:06

philwareham
Core designer
From: Haslemere, Surrey, UK
Registered: 2009-06-11
Posts: 3,564
Website GitHub Mastodon

Re: [docs] Github wiki

hcgtv wrote #292246:

Any chance of getting a dump of the wiki as it sits now?

Getting stuff out of the Wiki isn’t as straightforward as you’d think/like. I can (and have) exported chunks of it to XML, which I then need to cleanup and markup using Textile (instead of the wiki markup).

It’s a long laborious boring job, hence why I can only face it in small chunks.

What happens to it after that is up for debate, but I wouldn’t necessarily use GitHub Wiki for it. See my previous post. If you want a nice UI for the text editing then we can use prose.io.

Offline

#16 2015-06-29 12:59:21

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Re: [docs] Github wiki

I won’t touch anything. Kick me back out. Whatever. I didn’t know there was a specific road plan at this point.

Like for most users, my docs context is based on what is actually in place, which is .net and a few Github pages. Maybe the .net wiki homepage should point to an overview (wherever that might be) of the new docs agenda? Just a thought.

Offline

#17 2015-06-29 13:01:37

philwareham
Core designer
From: Haslemere, Surrey, UK
Registered: 2009-06-11
Posts: 3,564
Website GitHub Mastodon

Re: [docs] Github wiki

Bloke wrote #292253:

So what should we set up, and how, if people like Destry and Bert want to get involved with the documentation drive now?

I’d need to set up a Jekyl install on GitHub pages, which I’ve never actually done before. I will spend a few lunchtimes at work kicking the tyres of it and see where I get to.

In the meantime I have a XML files of Wiki pages if people want to convert/add them into the documentation repo to help me out. It might be best thought to wait until I have a proper GitHub Pages workflow in place.

Offline

#18 2015-06-29 13:03:25

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: [docs] Github wiki

philwareham wrote #292254:

Getting stuff out of the Wiki isn’t as straightforward as you’d think/like

Yowzers, that sounds nasty. Anyone would think they didn’t want you to export it…


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#19 2015-06-29 13:05:48

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: [docs] Github wiki

philwareham wrote #292256:

I’d need to set up a Jekyl install on GitHub pages

Sounds sweet, thanks. Sorry for jumping in, I forgot you’d mentioned Jekyll the other week.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#20 2015-06-29 13:06:27

hcgtv
Plugin Author
From: Key Largo, Florida
Registered: 2005-11-29
Posts: 2,722
Website

Re: [docs] Github wiki

Destry wrote #292249:

What site is that?

Phil was talking about moving the tags to a TXP site, saw it mentioned on a forum thread recently. I dabbled in moving the tags to a TXP site, have you seen txp:tag – Textpattern Template Tags ?

A single, official version of core system user docs is all that users should be distracted by. Outside of that it’s TXP Tips, etc.

Nobody wants to take over being the official Textpattern docs, but that doesn’t mean we can’t re-purpose some of the docs. Why re-invent wording that has been refined over many years. Think of new sites with refined purposes, promotional material, etc.

Destry, remember there’s always copy/paste, how do you think I did the Template Tags site if I had no dump?

Offline

#21 2015-06-29 13:07:19

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Re: [docs] Github wiki

Data export discussion makes me think it’s worth saying this…

Regardless of where the docs end up, I would not advocate a direct auto port/migration of content from one source to the new official location. That’s a fool’s move. Content should be manually picked, revised, and added from old place to new, leaving the crap behind in the process, whether in whole (as a page may warrant) or through proper editing. That’s the quality approach.

Offline

#22 2015-06-29 13:15:41

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: [docs] Github wiki

Destry wrote #292260:

I would not advocate a direct auto port/migration of content from one source to the new official location.

I concur. Most of the wiki docs are so far out of date (screenshots, etc) that it’s probably better to just find a doc that’s worth keeping, copy/paste the on-screen text into your favourite editor, hack out the cruft and edit what’s left, then stuff the result to the new location — taking into account the Style Guide which is knocking around on Google Drive (somewhere).

I’d be reticent to go down the whole annotated screenshot route again. It’s a ballache to maintain, and with various themes available, serves little use, even to novices. Even though a picture paints a thousand words, it can create a thousand times the pain to keep it up-to-date.

The only exception to taking the content lock stock might be the tag reference, which is fairly complete and fairly well structured, having been rejigged in living memory. We (*cough* Phil) already have all that ported into a decent format in the textpattern-documentation project, so most of the hard work for that is done, yay.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#23 2015-06-29 13:16:46

philwareham
Core designer
From: Haslemere, Surrey, UK
Registered: 2009-06-11
Posts: 3,564
Website GitHub Mastodon

Re: [docs] Github wiki

Destry wrote #292260:

Regardless of where the docs end up, I would not advocate a direct auto port/migration of content from one source to the new official location. That’s a fool’s move. Content should be manually picked, revised, and added from old place to new, leaving the crap behind in the process, whether in whole (as a page may warrant) or through proper editing. That’s the quality approach.

Totally agree, I’m rewriting portions of the docs as I go. That was kind of why I started with the tag docs, since they require the least amount of rewriting (updating some external links, better examples, that kind of stuff).

OK, I’ve created a GitHub Pages site to house the new documentation but I’ve run out of time today – will continue this tomorrow.

Offline

#24 2015-06-29 13:28:27

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Re: [docs] Github wiki

The Tag Reference has always been a thing unto itself. That is indeed a groomed piece of work that needs little editing, though many tag pages do need more/better examples, IMO. Some are pretty useless.

All the other pages (those deemed useful at all) could be improved tremendously. Content copied to a text file (forget Drive), edited, then pasted into new place as a first draft for shaping docs IA. That’s the way to go. The drafts can be revised once in place. Undoing an old IA after porting is backasswards.

I agree about images. They’re too much of a moving target and time investment. The trick will be to write more concise explanations; perhaps not detailing every micrometer of the UI, but the major stuff, and go from there.

Offline

Board footer

Powered by FluxBB