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.

Bloke · 2020-12-01 21:28:08

I’m in.

Destry · 2020-12-01 22:49:43

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.

Yep. Lots of useful bits and bobs but not well organized or visible.

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.

This collaborative focus on a given doc might work well when it comes time to actually shuffle words around on a page.

But — and I don’t mean to step on toes — I’d advise mapping out a plan before getting to that point or it could be a lot of wheel spinning.

Following is one approach to consider to get everyone in sync.

What is the overall Goal?

We know the docs are moving off github, and they’re going to stay as Jekyll pages, just not hampered by github constraints. Good. That saves a lot of markup work, styles development, etc. I would also suggest keeping with Markdown since that’s all done.

Stef has ideas for more dynamic handling of tag data. He’s probably the only one that does, so he can be in charge of that. ;) Pete, you’ll know what to do with platform setup. And Phil will be on hand if any new style work needs decided on, but that seems pretty covered to me. So far so good.

So what does need changed that can shed light on the main goal? That’s the question to answer here.

Is it the information architecture? Yes, partly. Last time we were at this junction, there was an effort to merge doc pages into more complete tutorials, while at the same time eliminate needless dead weight, such as admin-side panel pages that only explained the obvious. I think we were all on board with this, and the repo was working well to keep track of the consolidation effort and the resulting file tree changes. I recommend keeping on in that direction since a lot of ground was made.

Is it page level editing? Yes, again. Evident by the IA changes, necessarily. So this begs another question: what are the needed edits?

Now we start to merge two objectives into our overall goal. One objective is the consolidation of material into single-page tutorials, as mentioned previously, expectedly longer pages with contents lists and opening summary paragraphs being the norm. (The themes doc is probably a good example of a page too long, maybe. TBD.)

The other objective is what Pete is aiming for in this thread; finding and extracting all the useful intel in this forum that should be in docs but is not, then working that in as part of the docs changes.

This demands a process for the hunting/mapping. Let’s call it workflow.

Workflow

First, lets not waste what tools the repo already provides for collaboration, communication, and controlled editing. We can still take advantage of that to revise docs where they are and move a largely completed site to the new platform later.

What needs added with the second objective in mind is a way to map the forum tidbits to the respective pages they are deemed suited to go. If we remember the collab effort being developed in the repo, where every doc page has its own dedicated issue, then we can easily use those issues as a convenient way to bridge doc pages with forum links. Any forum bit that seemingly relates with a given doc, add that link to the issue thread with a brief comment why it could be worth considering.

If collaborators don’t want repo accounts for the ongoing link gathering/mapping phase, then, as Pete suggested, an associated goog doc could be created for each repo issue, too, where people can add forum links. Repo editors can then transfer that to issue threads.

This mapping, and the associated forum hunting/gathering of links is an important phase. It will greatly help keep the collaboration organized and moving forward.

Editing

Eventually, you’ll start seeing where the hunting/gathering phase for some topics/pages is exhausted and the actual developmental editing of a given page can begin. This will involve:

following up with gathered forum links per doc and extracting the valued info from the associated forum posts/threads.
organizing all the extracted info into a logical document flow
edit, revise, repeat generously.
use issue assignment protocols to edit between doc versions so no one steps on toes

What we might discover in the course of this work is the need for new doc pages or changes to the existing file tree. That’s fine, if so. It’s expected that we would by fact we’re fortifying docs with more information.

Does this make sense? The point is to not abandon what already works, or is a good idea, or can greatly facilitate the effort before it’s even necessary to move the installation.

Bloke · 2020-12-01 23:40:43

Word.

Textpattern CMS

Textpattern CMS support forum

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