[docs] Github wiki

Destry · 2015-07-03 08:40:16

I’ve got no problems with using Markdown. So much of what’s out there now adopts that flavor that I’ve become reasonably adept at both formats. I still like Textile better (just makes more sense), but gotta roll with the flow sometimes.

I’m very pleased that Txp will have the lightweight markup filters. Little things like that will get attention if it’s promoted right. Has big implications for more flexible editorial collaboration too, as most people will probably know Markdown before Textile and thus editors can accept that as a draft format.

philwareham · 2015-07-03 08:43:06

The only Prose.io drawback is that if you create a new document within it, then that file is a Markdown file. Otherwise, I think the workflow will work well for the documentation.

Will update with more info as I learn more.

Destry · 2015-07-03 08:46:06

So maybe docs editors need to be savvy of both formats and not worry about it if a given page is one or the other. I’m mean, seriously. It’s the rendered result that counts and we should be a little more ambidextrous anyway.

I’m a swinger!

philwareham · 2015-07-03 09:04:38

Destry wrote #292555:

So maybe docs editors need to be savvy of both formats and not worry about it if a given page is one or the other. I’m mean, seriously. It’s the rendered result that counts and we should be a little more ambidextrous anyway.

I’d rather keep docs in one format, preferrably Textile since the text could conceivably be repurposed for other things such as inline-help in Textpattern control panel one day. It’s not a problem though – authors using Prose.io in the short-term could save their Markdown as draft status, we could then convert to Textile. All existing docs are safe, as you can’t change the markup type in Prose.io of a doc once it is created.

For people using GitHub directly, they would just create a Textile doc as normal in their IDE/text editor and commit.

Destry · 2015-07-07 10:47:34

For what it’s worth, I spent a few hours porting Kaizen Garden’s Gdocs to a Github wiki. It was pretty easy, all in Textile, and on the surface looks usable. Voila!

Only problem is it needs to be pushed back up to the KG level, and I don’t know how to do that. Maybe I went about things wrong to start with… I forked the wiki (which was empty) built it at my Github location (whatever you call that), and now what do I do?

I know that’s out of Txp range, but any Github pointers would be appreciated (I seem to forget Github as fast as I learn anything there); they might be needed in a Txp context someday.

hcgtv · 2015-07-17 19:25:27

philwareham wrote #292552:

I’ve been playing with Jekyll for the docs and it seems to be an ideal fit, along with Prose.io to edit the files in a browser-based text editor for those who don’t want to fully immerse themselves in the GitHub model.

Phil, I’m going to convert the MediaWiki docs into DokuWiki, I want to see how they look. There’s a number of ways to get them into DokuWiki, just need to see which option is best.

I know you want to go with GitHub, but I don’t have the warm and fuzzies about relying on external services.

An added bonus of moving them to DokuWiki is that we’ll have flat files to do with what we please, convert them to Textile, whatever you so desire. I just want to get them out of the database.

philwareham · 2015-07-18 06:04:01

If you can zip up those exported Textile pages and send to me that would be great.

I will be using Jekyll to host the documents though, and keeping it version controlled.

I’m currently cleaning the RPC server and then I’ll be back onto docs.

hcgtv · 2015-07-18 11:59:44

philwareham wrote #293451:

If you can zip up those exported Textile pages and send to me that would be great.

Spent most of yesterday afternoon and evening cleaning up the wiki of all foreign languages and weird looking pages, the database has gone from 122MiB to 75MiB.

Today, I’m going to convert into DokuWiki format, then I’ll see how I can regex the DokuWiki format into Textile for you.

ax · 2015-07-18 19:02:07

hcgtv wrote #293469:

Today, I’m going to convert into DokuWiki format

Just in case that you are not aware of it anyway, there is some online tool could be useful for conversion of Textile into DokuWiki, or pandoc on the command line. For conversion of DokuWiki into Textile the doku2html tool has been suggested to indirectly convert into Textile, like this:

doku2html FILE | pandoc -f html -s -t textile

Last edited by ax (2015-07-18 19:32:19)

Destry · 2015-07-23 13:50:16

Phil,

I know you’ve pretty much decided on Jekyll, but I’ve been working with Github wiki a little bit more lately, and I must iterate and elaborate on the point I mentioned about it before, which is it’s really easy. Each time you start a new page with the “New Page” button, you have a list of format options:

*AsciiDoc

Creole
Markdown (default)
MediaWiki
Org-mode
Pod
Rdoc
Textile
reStructuredText

So if you need to quickly port a particular doc over in a particular format (e.g, MediaWiki) you can easily get it in the Github wiki for immediate use; literally a three-second create/paste/save/done process. In similar fashion, people can immediately start editing that page without waiting and facing learning curves with new tech/apps. As editors improve the copy, they can edit the markup too and save the page in the new format mode (i.e., Textile). Granted that’s not auto-converting the formatting of all doc pages all at once, but you can’t auto-edit the actual information in all the doc pages anyway (a human chore) so it doesn’t make a lot of difference; it all works out in the end.

Further. It’s easy. Did I say that? Nobody has to install Jekyll or the Jekyll editor (I forget the name), take time to learn it, push and pull things around, etc. People can just get to work right now and start making new usable docs instead of them being ignored at .net or hidden away wherever you have them kept at the moment.

And none of that is to say a Github wiki has to be the final destination. Consider it the humane middle stage where the docs IA is reshaped and the relevant doc pages are edited into final copy by a few more willing hands, and then you take them at your leisure, as they are done, and put them in a Jekyll location where you can add your sexy presentation layer — because I know that’s what the real motivation behind Jekyll is, right? Sex! It’s certainly not for the sake of facilitation. :)

In fact, as I write this, it makes me realize this could all make for a workable rights of access and quality control model, not to mention a clear plan for getting the docs project done:

Bert makes his cleaned up MW-to-Textile converted pages available somewhere as text files, or whatever, for willing editors to have access to.
Editors, like myself, with the global auditing effort in mind, pluck those pages as we see fit for creating the new docs IA and build that in the sandbox Txp github wiki (e.g., github.com/textpattern/docs.textpattern.com/wiki). This is the docs collaboration phase.
You and/or Team Txp pulls that over — by whatever means/desire/mode/timeline/drug — to Jekyll, and only authorized peeps have access to that.
When the beast is more or less finished, or at least in a tapering-off state, we can decide to pull plug on the sandbox wiki and anyone interested in maintaining editing rights can raise their hand and be given Jekyll rights of access. All maintenance efforts then goes there.

I won’t bring it up again, but just wanted to elaborate the case more specifically so we’re thinking about options from all angles. I have nothing against leadership choice to use the platform it chooses, but arguments can be made for facilitation, leverage, and ease of contribution, considering the long road ahead.

Bloke · 2015-07-23 18:29:04

Destry

Your ideas are intrigung to me and I wish to subscribe to your newsletter.

Translation: I like the immediacy of getting people on board to help with the documentation effort now and then moving it (if at all necessary) later. If we do go with something like this then we just need to make sure docs are only available for editing in one place so accidental duplication of effort is avoided.

Destry · 2015-07-23 19:01:00

I’ve been known to be too forceful with my ideas and input, and sometimes my humor does’t go over well, so please don’t let me bend anyone’s arms. I’ve no objection with Jekyll. Indeed, it would allow giving docs a brand presentation whereas the Github wiki wouldn’t (if that was really a big deal). But, as you rightly identify, my idea would allow doc editing yesterday, and as long as that editing was in the github “sandbox” wiki, then there shouldn’t be concern for duplication, though I could be overlooking something? Ultimately, I respect what Phil wants to do since he has valiantly burdened the thankless yoke that is user docs.

Textpattern CMS

Textpattern CMS support forum

#61 2015-07-03 08:40:16

Re: [docs] Github wiki

#62 2015-07-03 08:43:06

Re: [docs] Github wiki

#63 2015-07-03 08:46:06

Re: [docs] Github wiki

#64 2015-07-03 09:04:38

Re: [docs] Github wiki

Destry wrote #292555:

#65 2015-07-07 10:47:34

Re: [docs] Github wiki

#66 2015-07-17 19:25:27

Re: [docs] Github wiki

philwareham wrote #292552:

#67 2015-07-18 06:04:01

Re: [docs] Github wiki

#68 2015-07-18 11:59:44

Re: [docs] Github wiki

philwareham wrote #293451:

#69 2015-07-18 19:02:07

Re: [docs] Github wiki

hcgtv wrote #293469:

#70 2015-07-23 13:50:16

Re: [docs] Github wiki

#71 2015-07-23 18:29:04

Re: [docs] Github wiki

#72 2015-07-23 19:01:00

Re: [docs] Github wiki

Board footer