Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#11 2020-12-01 19:02:34

gaekwad
Admin
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 3,344

Re: Docs site refresh effort

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.

Offline

#12 2020-12-01 19:11:53

WebmistressM
Member
Registered: 2011-08-12
Posts: 61

Re: Docs site refresh effort

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.

Offline

#13 2020-12-01 21:28:08

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 9,977
Website

Re: Docs site refresh effort

I’m in.


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

Offline

#14 2020-12-01 22:49:43

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

Re: Docs site refresh effort

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:

  1. following up with gathered forum links per doc and extracting the valued info from the associated forum posts/threads.
  2. organizing all the extracted info into a logical document flow
  3. edit, revise, repeat generously.
  4. 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.

Offline

#15 2020-12-01 23:40:43

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 9,977
Website

Re: Docs site refresh effort

Word.


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

Offline

#16 2020-12-02 00:38:25

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

Re: Docs site refresh effort

A different workflow will need conceived in the future, though, assuming docs won’t be under versioning at that point. Docs and editing are like code — a never-ending process.

Offline

#17 2020-12-02 09:35:50

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

Re: Docs site refresh effort

For people who want to help but don’t have the history with Txp docs dev/editing as some of us do, and might be confused or inhibited by the aforementioned github workflow, a good and important way to dive in immediately with this effort is:

  1. start identifying topics that are seemingly missing in docs and are deemed needed, and make a list of those topics
  2. make sublists for those topics that provide links to forum threads or individual posts having answers or relevant explanations that would help draft the needed doc
  3. make those lists publicly available so collaborators can see them.

Only focus on topics that have core Textpattern solutions, not those relying on plugins.

Don’t worry about actually drafting docs until we get a fair number of such topics identified and supported by forum material, and then prioritized for development. Drafting and editing will come later in context of repo and versioning, and editors will help with suggestions about where info might go in the file tree.

Also, no topic is too simple. The bar on this is low. For example, how to add a logo is a common question new users have, and repeatedly asked/answered in the forum. Our goal will be to identify those topics, write docs for them (or work the info into suitable existing docs), and point people to a relevant doc in the future if a person doesn’t already find it self-sufficiently.

In fact, that should be your audience perspective when making topic lists — new users of Textpattern. As well any questions you might have of your own and not addressed anywhere in docs.

Once we seemingly exhaust identifying missing topics, we can turn more collective focus to identifying forum threads and posts (better) that hold valuable information for augmenting existing doc pages. That’s also a critical part of the overall goal.

Last edited by Destry (2020-12-02 10:07:10)

Offline

#18 2020-12-02 09:54:02

gaekwad
Admin
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 3,344

Re: Docs site refresh effort

Destry – thank you – agree with you 100%.

Offline

#19 2020-12-02 09:59:35

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

Re: Docs site refresh effort

Cool. We have a way forward.

Last edited by Destry (2020-12-02 10:00:12)

Offline

#20 2020-12-02 10:20:40

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

Re: Docs site refresh effort

Another way to identify topics is come up with better tag examples in tag pages. A lot of existing examples are either too generic or relying solely on the markup to make them clear, which of course they are not without accompanying context and explanation. Examples that reflect a variety of real use cases in the wild are best, from simple to more complex (such as extended attributes and related logic).

Offline

Board footer

Powered by FluxBB