proposed: Collaboration on user documentation

[wion]

URLs:

back: https://github.com/textpattern/textpattern.github.io/blob/master/brand/user-docs-collaboration.md
front: https://docs.textpattern.com/brand/user-docs-collaboration

Scenario

A doc for recording collaboration procedures, and reference thereafter. This is a new issue for the effort. This is not the same thing as the docs authoring/editing guidelines, which concerns content development.

Resources for consideration

1. researching docs collaboration procedures #116
2. Collaboration guidelines test run
3. Images in docs
4. File naming convention
5. Redirecting
6. Txp github teams

To-dos

Some reflection on the above resources might be needed.

• A workflow diagram to help visualize doc development from ideation to publication.
• A 'Get help' section at end. (Where should the help link point to? Should we talk about roles here, as might be reflected in item 6 above?)
• A section addressing use of images? (Using images is a lot of tedious work, let's remember, see item3 above. This section would be small, though, because how to actually use images would be fodder in the development guidelines.)
• Revise Issues templates to change checkbox lists in the 'Resources...' section to just bulleted lists, and update doc to suggest checkbox lists are useful after issues are created to list sub-tasks for main tasks (as doing here).
• Work in any relevant bits from item 2 above.
• Work in any relevant bits from item 4 above.
• Ensure item 5 above is sufficiently outlined.

[wion]

I had this file started a while back with quite a bit of content in it, but it seems to have disappeared. I don't know what happen to it; might have been during my repo conflict problems I was having. Don't know. Anyway, this is a fresh issue to start fresh.

[wion]

Wow. Nearly a year. This is first tiny step on the dark side of the moon.

[wion]

First draft pushed to fill the hole. I would appreciate anyone giving it a once over too see what they think is missing. I'm sure it will arise eventually regardless.

I've put the 'Editorial workflow' section off for now, but hopefully that won't need much after folks get used to the labeling system. An example workflow might be good though.

I'm thinking it might also be good to add a section for who is most expected to do what in the workflow and assignments as they relate with labels. New collaborators will need this, I think.

Might need to fix a link or two that points to the doc. Can't think where they all are off-hand.

Oh, there might also need to be more clarification on how listed topics from the forum are evaluated and who ultimately does that. Let me know what you think on that.

@Bloke (heh)

[petecooper]

First pass from me done, made a few very minor tweaks.

Observations in no particular order:

• Lots of text, which is fine, but the barrier to entry will be higher as a result.
• Is there value in assigning stages to each issue tag as part of an overall diagram or flow chart? Something visual for people to see where they are in the new doc / revision process would perhaps be sensible for people who have spent time editing words. High level: split the process into no more than 5 steps (prep, drafting, editing, publication, revision or similar), with each stage having tags, so when the author or editor looks at the doc / issue, they have a "you are here" marker, and can find their way relatively quickly
• Perhaps scope to mention a route to ask for help? We'll have relatively few contributors and we need to make it low friction for this to work. Hell, have a drop-in forum thread, Jitsi session, whatever – something outside GitHub where humans are.

I'll take another look with fresh eyes tomorrow, leaving my assignment on until at least then.

[wion]

Thanks, Pete. I actually squeezed in some small additions/revisions around your minor tweaks without following proper collaborative protocols. Bad Destry! I didn't think anyone would be so quick. But there you were. Luckily your changes were indeed minor and no conflicts occurred.

Yes, lots of text, dang it The appearance of which is made worse by the wide layout of the docs website, IMO, but that's something else. Maybe I can whittle out more needless words here and there with some more editing passes of my own, but I think the scope won't change much. I haven't even added the section on using images (or not) yet, and who knows what else might surface.

Yes, a diagram or two might break up the text. I've no objections to that, though I'm a little brain-dead for thinking about one. I'll add that as a to-do in the head post here.

Sketches to the idea are welcome. Maybe the workflow section could be augmented with, or even changed to, a circular diagram to show that collaborative repeating loop? (Images must be accessible, though, and conceptual diagrams are hard to make that way, so maybe the text remains in the respect.) As for what steps should exist, I think that just depends on what actually works. We might have to wait and see what rises and where the friction actually is. Whatever the case, I've no intention to tell people to do what they won't. ;)

A Get help section at the end? Sure. I'll mark that in the head post to-dos.

Making docs like this is always a thankless job, which is probably why I've put it off so long.

This doc's long term value for people is probably not to read it start to end, but to come back to it periodically and jump to a particular section via the contents list, like like the associated docs development guide. A reference doc. In that respect, whether it's one long doc or many short cards, as some help systems favour, I don't think it really matters. And when people can download these as printed mini-manuals to have offline, that might also favour a single file.

[wion]

Remembered that the checkbox lists suggested in the Issue templates create those progress bars in Issue headers. The checkbox lists are useful, but that behaviour in this context is not. So, I'll probably revise those lists in templates to be just bulleted lists, and suggest in the procedures that adding To-do sections in the head posts of Issues can be useful when it's clear that sub-tasks are needed to complete a given main task.

[wion]

We'll have relatively few contributors

That is a true statement, and probably where I always go wrong with these help things; I write for a bigger audience than exists.

Oh well, this box is ticked, finally.