Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
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
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
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.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
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.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
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?
We Love TXP . TXP Themes . TXP Tags . TXP Planet . TXP Make
Offline
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
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.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
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
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
Re: [docs] Github wiki
@Destry: +Lots.
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
Re: [docs] Github wiki
Cool. It’s good to know there are people interested in the documentation stuff. I will endeavour to make a nice GitHub workflow that makes this all as painless a possible – just give me a few days.
All this rests on whether we have DNS controls for the textpattern.com domain name, so I can eventually repoint it to the GitHub Pages site (via Cloudflare).
Offline
Re: [docs] Github wiki
philwareham wrote #292267:
just give me a few days.
Awesome, thanks Phil.
All this rests on whether we have DNS controls for the textpattern.com domain name
Presumably that also affects things like the proposed themes.textpattern.com too? Or are subdomains under our control?
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
Re: [docs] Github wiki
Bloke wrote #292268:
Presumably that also affects things like the proposed
themes.textpattern.comtoo? Or are subdomains under our control?
New subdomains would also need DNS record access, so I’m hoping Dean Allen gave that to us at some point in the past.
Offline
Re: [docs] Github wiki
Destry wrote #292264:
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.
You know Destry, I’ve linked to my Textpattern Template Tags site on a few occasions in threads where you were very active. Not once have you said anything, you dismiss the post reply, like I never posted anything.
There in lies the problem with Textpattern, contributions outside of the walled in Textpattern world are not really welcomed. Sure, dive in and contribute, if you can gain access that is. I remember when I first joined the community, it was a mission to get access to the wiki, and then your access would go poof on a MediaWiki update.
Yet here we sit, with TXP branded sites like TXP Magazine, with no new content in 2 years. Yeah, we’ll get to it, and the Internet years wizz by.
Destry, I could make a clone of the wiki in an afternoon. The reason I wanted the dump was to see historical changes to pages, who changed what and why – especially the tag reference.
There’s more to running an Open Source project than just buying up sites to protect your brand.
We Love TXP . TXP Themes . TXP Tags . TXP Planet . TXP Make
Offline
Re: [docs] Github wiki
hcgtv wrote #292271:
There in lies the problem with Textpattern, contributions outside of the walled in Textpattern world are not really welcomed. Sure, dive in and contribute, if you can gain access that is. I remember when I first joined the community, it was a mission to get access to the wiki, and then your access would go poof on a MediaWiki update.
I’m not really sure what is being said here, sorry – I can give you a dump of the MediaWiki if you need one, it takes time to export from the wiki though as I have to take each section as an XML file (they don’t give you an easy method to export from their software).
But there is already a fairly well advanced collection of tag documentation that I have already exported from the wiki, rewritten and converted to Textile for use in a version controlled flat file documentation site (hence why the decision was not to use Textpattern to power it). I can give you (or anyone who wants it) commit rights to it if you have a GitHub user account and willingness. In fact, I’d prefer it to working alone.
Those Textile documents are open source. so anyone can repurpose them for other uses (in their own site, for a book, etc.). I’m sure there is plenty within your own tag site which would be very useful in the new docs site too.
Offline