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.

[wion]

@Bloke, Was just checking the templates. Not sure how you managed to have the prefixes added to the subjects fields, but cool!

One oddity, though, each template gives the same page title after the prefix, this one:

page: Front-end themes

It could be my unclear request. What I was hoping for was just this:

page:

And then the person starting the issue would add the title as needed. Same deal with the other template.

Since you seem to be able to pre-fill the subject field with a prefix, we don't need any of those instructions in the body. Just this would do fine...

--------------------------Template name: 'Discuss existing page' -----------------------
Absolute URL of front-end page:

{URL here}

The question/problem:

{Put it here}

--------------------------Template name: 'Propose new page' -----------------------
Proposed page topic:

{Propose here}

Reason page is needed:

{Explain here}

Perceived doc-tree location and cross-links:

{Suggest here}

[Bloke]

Removed template instructions.

I haven't actually completed a new issue, but if I start the process, the subject line shows the prefix and nothing else:

page:

Not sure why you're seeing additional page fodder in the subject.

[wion]

Thank you, Stef!

That same page title name keeps appearing for me in the subject field, for some odd reason, but the rest looks great. If it's just my problem, then that's fine. I can edit it out each time. It must be due to me having edited that page recently; how else would that page out of over 100 randomly appear? Strange.

Maybe a third person (@petecooper ?) should try a template and see how it appears. If no title, then no problem.

[wion]

We could put the link to the [doc team] location in the project's main ReadMe.md . . .

In this line of conversation (and as part of my info gathering for the collaboration doc), I have a couple more questions for the team. Assuming posts made in that docs team location are visible to the public (none team members), then:

1) What would be the unique value of posting there, and for who?

Here's one way to look at...

In general, our aim is for Issues to be 'inbox zero'. That's the ideal state. No issues means no one has extra work to do. We must be doing something right if there are no issues. In that pursuit, we don't want to use issues for anything there isn't an issues template for (if we need to create another one, fine). One of those kinds of non-issues topics would be team/editor discussion around collaboration, architecture changes, and so forth.

For example, this issue we're in now would not have been made here, in fact, but posted as a team conversation in the team channel. Issues would only be for the community at large (including editors) to raise questions/problems about text/matter on documentation pages, or propose new ones.

Ideally this would be a 1:1 relationship between Issues and doc pages. When an issue — having subject heading 'page: Title of page' — is closed, and that page later needs an issue raised again for whatever reason, the dedicated (closed) issue is found and re-opened. This keeps a documented record of problems for a given page in one place. No redundant issues creation.

Does this high-level look at it makes sense? Other ideas?

2) Where should editors pose to the graphics design team of one any transparent requests for new or altered element styling?

In other words, requests being relevant to the docs-base as a whole. Here in issues? In the docs team channel? In the designer team channel? Other?

Realizing, of course, there is a standard brand presentation that rules the great majority of presentation across the project, I also find there are a few situations where certain content elements/types could be presented more clearly and appropriately, notably with the simple inclusion of specific class selectors and use of Kramdown. These specific presentational cases would be defined in the user docs guidelines under an appropriate Markup location.

Before I, or anyone, else raises such issues, where should such issues be raised?

[wion]

1. What would be the unique value of posting there, and for who?

Just realized that those posts have two visibility settings to choose from. Either:

• everyone in the Textpattern Github 'organization', or
• just the team and docs repo administrators (which is just about everyone in the TGO anyway).

Anyone else in the community, or anyone not logged into Github would not see anything either way.

So, that's good. That means we can use that to discuss high-level topics (e.g. collaboration procedures) that don't need belabored in regular docs issues.

That just leaves question 2.

[philwareham]

Regarding question 2: You can raise an issue on the https://github.com/textpattern/textpattern-com-website repo (as the CSS on that site powers the docs site too) and add @philwareham to the message - I should get an email notification and can then track the issue. Otherwise these requests would get lost within various thread conversations.

I'll then consider and fix the issues as I get spare moments in work. Cheers all.

[wion]

Great. Thanks, Phil. I'll write that into the collab procedures.

[wion]

Starting a fresh issue on this one, #149.