Open wion opened 4 years ago
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.
Wow. Nearly a year. This is first tiny step on the dark side of the moon.
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)
First pass from me done, made a few very minor tweaks.
Observations in no particular order:
I'll take another look with fresh eyes tomorrow, leaving my assignment on until at least then.
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.
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.
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.
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
116
To-dos
Some reflection on the above resources might be needed.