Docs site refresh effort

gaekwad · 2020-11-05 15:48:45

We’re hoping to release Textpattern 4.8.4 around the end of November. That’s the time in the north hemisphere when the daylight hours are shorter and you may choose to top-up your screen tan.

I’ve been thinking about the content of the docs site recently, and how we have a wealth of information stored in this forum, including code snippets, tips, tricks, and similar things.

I would like to address some of this starting in November, and one idea I have been considering is having a one-docs-page-per-week focus, and inviting anyone with snippets, tips, tricks or similar things to collaborate on the editing process. We can add examples, explanatory text, things to avoid, recommendations, that sort of thing.

As an example, we could start with article tags, then perhaps tweak the installation docs, then move on to themes, then some administration, and so forth. This is not a high pressure task, and we can find the right pace with the people involved so it becomes a useful exercise and not a chore.

Essentially, having more eyeballs and more years of Textpattern experience combined will, I believe, make for an even better docs site – and we all benefit from that. Other side-effects will be refreshing skills on aspects of Textpattern that we may be out of practice with, or even brand new things that we didn’t know existed.

What do you think? If this idea has your interest or attention, would you like to be part of the docs refresh team?

Feedback, advice and anything else very welcome.

Over to you.

gaekwad · 2020-11-06 10:46:55

I should clarify to avoid any confusion. When I say:

[…] having a one-docs-page-per-week focus […]

…I mean everyone involved all looks at the same thing (e.g. @<txp:article_custom>) at the same time (e.g. week 12 of 2021), effectively curating content for each document in turn, with the hive mind / wisdom of crowds effect making for a better document.

Obviously we can come back to anything after the fact, but having eyes on the same thing will, I am confident, make for a better docs site for everyone.

colak · 2020-11-12 07:07:53

Hi Pete, I’m acknowledging reading this one. We have huge issues here with the soft lockdown and deadlines for funding next year. I will help during x-mas when I’ll hopefully get some time to breath.

gaekwad · 2020-11-12 07:32:47

Thanks, Yiannis – please focus on what you need to do, that’s your priority.

Bloke · 2020-11-12 08:11:50

I think this is a fab idea to help get the docs in shape. Meant to reply sooner.

The docs have been left behind a tad so it’s a great opportunity to seed out the cruft and rewrite/consolidate the docs in a more user-centric, topic-based (rather than panel-based) manner, that Destry started doing before.

On board. Let’s pick a page and blitz it.

gaekwad · 2020-11-12 09:31:20

Nice one, Bloke – thanks.

I’m open to how best we approach this with regards to planning and execution. Currently I’m erring towards doing a page per week, with a proviso that anything else is fair game if we see easy wins and we can have additional time for more complex pages. (i.e. I doubt it’ll take a whole week to work through site_slogan, whereas some of the article ones will be a bit more time-consuming.

Given we have 4.8.4 due out in two weeks-ish, I propose we focus efforts on that as the priority and start mapping out scaffold for how we can sustainably do docs from December onwards. Getting the docs work flight plan sorted during December gives us a nice way to start 2021 in week commencing January 4th (aka week 1 in calendar terms).

I’d also like to have a low barrier to entry, so people here who are not familiar/comfortable with git/GitHub can still assist by finding code examples, suggest edits and so on. We could have a side aim of encouraging issues and pull requests to increase the overall knowledge of git/GitHub operation as some momentum builds. We don’t have a docs forum or subforum – nor do I necessarily think that’s the best approach – but somewhere to gather all the work discussions here would be beneficial, as long as it’s not a humongous single thread that encompasses all the pages.

I’m open to advice and feedback on all the above.

Destry · 2020-11-12 09:45:33

I do mean to get back to it at some point, though not at the intensity I was burning the candle before. Apologies for again leaving things hanging.

I would not be much help with tag docs, so will stay out of that fray, but I‘ll pick up again with the consolidation efforts of other doc files and editing that Bloke mentioned, which is challenging enough. I also think the new index (index2, temporarily) was a worthwhile faceplate, and the situation as a whole is not far from switching to that, I think. A couple of gaps yet, maybe, if I recall.

There was also a hanging matter of collaboration docs (i.e. docs detailing how to help with docs in a productive manner), but writing those is as complicated, if not more so, than updating user docs themselves, and nobody cares about them anyway. So aside from the yet finished general Txp style guide, and the docs development guide that is more or less finished, I don’t think it’s worth pursuing more on that front, and thus I should clean up that obscure trail in the file tree, too.

Just need to find myself again. Since the covid thing started many months ago now, chez wion has not been the same. We’re still trying to figure out this new norm of everyone being home all the time and irritating each other. I have less idle time for the computer now as a result (rather more time for peacekeeping, cooking, toilet cleaning, etc). And what time I do manage to find has been going to the almanossary project (so very far off yet). I cry every time I look at the Full Point and all the half finished drafts for that.

I should also say I will probably drop out of GitHub eventually. It just seems to get increasingly more Linkedin-like, and that turns me off, so once docs are somewhat shook down again, there will be that. I sometimes wonder at Txp’s reliance on GitHub, but that’s not a chestnut I mean to kick up again. I know Phil threatens to leave the project whenever it does get kicked. As long as I can download things I need without an account, and there’s some neutral place to shout things up the pipe, I have no real gripes.

gaekwad · 2020-11-12 10:26:04

Destry wrote #326716:

I do mean to get back to it at some point, though not at the intensity I was burning the candle before. Apologies for again leaving things hanging.

Thanks, Destry – from my view of things, you have absolutely nothing to apologise for.

Just need to find myself again. Since the covid thing started many months ago now, chez wion has not been the same.

Yeah, I hear that loud and clear. I spoke with a good friend of mine a month or so back, he’s in disaster management and business continuity. The gist of what he said that resonated with me was that people (and orgs, by extension) who will succeed are the ones who adapt to a post-COVID world.

hcgtv · 2020-11-15 20:24:36

Dang, a Database Schema, super nice guys.

I remember asking for a schema from Zem and being ignored, like it was a trade secret or something.

From what I see of the view source, the pages are on Github, then Jekyll is used to generate the static pages for the docs site?

To get a local copy, I did a save page in Firefox, would be nice for the future to have a download button on pages, so you can save them off, in PDF would be nice.

gaekwad · 2020-11-16 07:21:01

hcgtv wrote #326796:

From what I see of the view source, the pages are on Github, then Jekyll is used to generate the static pages for the docs site?

github.com/textpattern/textpattern.github.io is your friend.

would be nice for the future to have a download button on pages, so you can save them off, in PDF would be nice.

We’re working on compiling to offline formats (see #162 for info) and printing to PDF would probably be the most straightforward solution in the meantime.

gaekwad · 2020-12-01 19:02:34

Alright. It’s December 2020. Textpattern 4.8.4 has safely taken off. The daylight hours are short where I live, and so I’m taking the docs refresh on as one of my evening / weekend project. Heck, if nothing else, I might be a better writer at the end of it.

I would like to ensure low barriers to involvement, and for any participants to be comfortable with the tools selected. With that in mind, I propose we start co-ordinating here, and then use a shared Google Doc to schedule the various components we’ll be looking at, and GitHub for the changes we want to make.

If you’re willing to be involved in something that might take a year – and you decide your level of involvement / commitment – would you be comfortable using Google Docs and GitHub as we find our way?

Now is the time to say something if these things are not right. I have a to-do to get my head around OpenProject but it’s down the list and not an urgent thing, especially since we have ‘easy’ tools at our disposal. I’m not saying they’re the best tools for the job, but they’re out there and we can fine-tune as we go.

WebmistressM · 2020-12-01 19:11:53

Id like to state that I would definitely be on board for helping on documentation things. I know you are using Github as one spot for the doc, and then the main site here (https://docs.textpattern.com/). Although not relevant to textpattern, I do have experience managing and migrating data…as well as experiencing building wikis.

Textpattern CMS

Textpattern CMS support forum

#1 2020-11-05 15:48:45