researching docs collaboration procedures

[petecooper]

This might be part of a wider style guide/reference conversation, but is there a preferred way or standard for annotating docs that need work? There are various versions of todo dotted around, some notes-to-self from @wion and various other bits and pieces.

From a front-end perspective, presumably it's better for the parsed Markdown to have some sort of visual marker on what's an author comment…or even just hidden from view on the front, but visible in source, or something else.

Am I missing something that's already been decided? If not, shall we toss this around and decide on some markup for meta comments that relate to the document itself?

[wion]

We could/should be able to use issues here well enough, but it might take putting some basic collaboration conventions into practice. Some thoughts...

1. For any given doc page where there's a reason for discussion, start a dedicated issue for it. This is a 1:1 relationship. The issue can be closed and reopened over time, as needed. One issue per doc page as the norm. The equivalent of a wiki 'talk' page. This implies searching for a potential dedicated page before jumping straight to creating a redundant one. ;)
2. For all such 'doc discussion' issues, begin their title with a distinctive prefix (e.g. discuss:) to help call it out, followed by the name of the doc page in question (e.g.discuss:themes-panel). That immediately says which doc the issue is for, and it can be reused at any time in the future. Easy to search for, etc.
3. Use new issue labels to help focus immediate conversation. We might need to think first what 3 to 5 labels we need and create them, but once there, they can keep the conversation focused on immediate issues and moving forward. Possible label ideas:
   • text needed (when new text needs written; use this label and clarify what text is needed)
   • editing needed (when new text needs reviewed by new eyes; use this label and clarify where editor should focus)
   • technical proof needed (when it needs a dev's insight from a tech validity standpoint)

That might be enough labels. A discussion needed label wouldn't be necessary because that's implied by the issue itself. It just needs clarified in the issue what the priority problem is at any given time.

We also want to know who to assign (hand-off) an issue to when new issues are created and labels change, otherwise it's easy for people to overlook the issues and they never get addressed. Having at least two people on standby for each label category is probably a good idea. If one can't get to it right away, the other hopefully can, etc.

Something like that?

[Bloke]

Since pages are in the repo, using Issues as suggested makes way more sense than adding todos in the publicly visible docs themselves. Side benefit: issue assignment to project members, tracking of open/closed stuff, '@' notification pinging and all that good stuff.

If I spot any todos during my day-to-days around here, I'll remove them from the offending article and if it's not a quick fix or needs further discussion I'll open a corresponding issue.

We can perhaps use Issue templates here like we've done on the main site where we have a pair of issue templates set up. Can templates have placeholders in the subject too? So when you click the 'page discussion' template it puts in:

discuss: <type-name-of-page here>

as the title, and then any salient stuff for the body? I've not made any templates so I'm not sure of the capabilities.

[wion]

Templates sound good. I didn't know they were possible. :}

[Bloke]

Yeah, for the main repo you can see them in action here if you pretend to make a new issue: https://github.com/textpattern/textpattern/issues/new/choose

Those aren't great examples, but the point is, you can design any body content you like so if we identify use cases, we can make (e.g.) a 'Content discussion' template which guides the person through the process of creating one in a standard format.

[Bloke]

btw, the labels we have defined are here: https://github.com/textpattern/textpattern.github.io/labels

Feel free to amend if you have rights (I think you do) or suggest alternatives that are useful, not only from a standpoint of someone raising an issue, but also for us to respond if the request is misguided or has some other outcome besides attending to it and closing it normally.

[wion]

I am working on two things at the moment.

One is the general editorial style guide, which I'm balancing with the user documentation guidelines and any other domain resources that pop up in the future. I hope to have a first solid draft of that available by end of weekend.

The other is a fleshed out plan/proposal for author/editor collaboration, as this issue rightly raised as lacking. For the moment we'll consider it a proposal for review. It will raise more questions needing discussed before it becomes a working procedural document. But it should be interesting for you, raising some looks ahead to the other platforms coming, and possible adjustments to docs handing with that in mind. Other things too. ;)

This latter doc should also land this month. There's a lot of cross-linking, redundancy-killing, context-forming, etc between the accruing docs I'm working on, so it's creeping along, but these resources will become interesting once they're in place and navigable.

Stay tuned. I'll close this issue when proposal is available.

[wion]

Changed the title of this issue. The original title topic will be one of many things covered in scope of the doc.

[wion]

@Bloke,

Can you create the two new issue templates below, at least the first one. The body instructions wouldn't even be needed if there was a way to prefix the subject fields with 'page: ' and 'proposed: ', respectively. I don't know if there is. Otherwise, this is the next most simplified way I can think of to get the minimum data and labeling. Suggestions welcome. I will reference these in the collaboration doc I'm working on.

--------------------------Template name: 'Discuss existing page' -----------------------
Instructions:

1. In subject field use: 'page: Title of documentation page'
2. In the issue body:
   1. Paste the page's absolute URL to the front-end location at top of issue for quick reference and link.
   2. State your question, or perceived problem with page, under provided section below .
   3. Delete all of these instruction lines when done, and before submitting the issue. ;)

The question/problem:

--------------------------Template name: 'Propose new page' -----------------------
Instructions:

1. In subject field, use: 'proposed: Title of new documentation page'
2. In the issue body, respond to the sections below.
3. Delete all of these instruction lines when done, and before submitting the issue. ;)

Proposed page topic:

Reason page is needed:

Perceived doc-tree location and cross-links:

[wion]

Also, is there a way to put a link to this docs team location in context of this repo? Because that's going to be worked into the collaboration doc too as part of the collaboration org structure, and it would just be nice to have it more accessible here too. The current hassle of going to HQ to find it via teams there pretty much buries it. At least the docs will provide it.

[Bloke]

@wion Done.

[Bloke]

We could put the link to the team location in the project's main README.md so it appears on the front page of the GitHub page. Would that do?

[wion]

That would be another location. No rush. I can do it when I get to the point of mentioning it in the collab doc.

Thanks for the templates.