search

w3c / horizontal-issue-tracker

Tools and pages to track horizontal issues
https://www.w3.org/PM/horizontal/
MIT License
6 stars 4 forks source link

Editorial and styling changes to the HOWTO #24

Closed xfq closed 4 years ago

r12a commented 4 years ago

I propose to take a step back in order to factor this into the bigger picture.

As i see it, there are two key documents for WG folks:

  1. The main Guide page at https://www.w3.org/Guide/, which for details links to the
  2. DocumentReview page at https://www.w3.org/wiki/DocumentReview

Then there is this document in the w3c/horizontal-issue-tracker repo.

Here's what i propose we do:

  1. Add a new section to the main Guide page at https://www.w3.org/Guide/ just below Specification Development with a title such as Getting Specs Reviewed. (Point to this from the subbullet in the previous section that currently begins with "Request Wide & Horizontal Review..."). The aim is to raise the visibility of the location of this information (because even i have to resort to searching for it on the page, and usually miss it the first time because i tend to search on 'horizontal'.

  2. From that section essentially just point to the DocumentReview page at https://www.w3.org/wiki/DocumentReview

  3. In the DocumentReview page create a new subsection entitled something like "Working with Review Labels". At the beginning of that section, give an overview using the text of the section "For Working Groups" at https://w3c.github.io/horizontal-issue-tracker/HOWTO. Then either follow that with an FAQ-style set of questions or point to https://w3c.github.io/horizontal-issue-tracker/process-faq. That document contains useful specifics and addresses questions raised by Ivan.

  4. Also point to https://github.com/w3c/horizontal-issue-tracker for those eager WG folks who want to look at the tracker pages.

  5. Reword the prompts (and maybe change text that needs it) in https://w3c.github.io/horizontal-issue-tracker/process-faq. Probably rename it as label-faq. Replace the final section in that document, about the director, with the text in https://w3c.github.io/horizontal-issue-tracker/HOWTO under the heading "What happens to unresolved issues marked *-needs-resolution?"

The net effect of these changes is that WG folks have a single point of entry in the Guide, they can get most of the information they need from the DocumentReview page, but they can get some additional information related to label handling if they want. Horizontal review folks can start with the https://github.com/w3c/horizontal-issue-tracker and find the more specific information they need. The WG folks can, but don't need to be sidetracked by stuff that is written for the benefit of the HR groups - instead we avoid inflicting them with verbiage about non-WG related stuff.

Thoughts?

xfq commented 4 years ago

Thanks for the hint Richard. It looks good to me.

samuelweiler commented 4 years ago

I propose to take a step back in order to factor this into the bigger picture.

As i see it, there are two key documents for WG folks:

  1. The main Guide page at https://www.w3.org/Guide/, which for details links to the
  2. DocumentReview page at https://www.w3.org/wiki/DocumentReview

Then there is this document in the w3c/horizontal-issue-tracker repo.

Here's what i propose we do:

  1. Add a new section to the main Guide page at https://www.w3.org/Guide/ just below Specification Development with a title such as Getting Specs Reviewed. (Point to this from the subbullet in the previous section that currently begins with "Request Wide & Horizontal Review..."). The aim is to raise the visibility of the location of this information (because even i have to resort to searching for it on the page, and usually miss it the first time because i tend to search on 'horizontal'.

Fine.

  1. From that section essentially just point to the DocumentReview page at https://www.w3.org/wiki/DocumentReview

My only worry is about the word "essentially". Please do not duplicate information. We're still changing these processes; let's have only one place to change the documentaion.

  1. In the DocumentReview page create a new subsection entitled something like "Working with Review Labels". At the beginning of that section, give an overview using the text of the section "For Working Groups" at https://w3c.github.io/horizontal-issue-tracker/HOWTO. Then either follow that with an FAQ-style set of questions or point to https://w3c.github.io/horizontal-issue-tracker/process-faq. That document contains useful specifics and addresses questions raised by Ivan.

For the love of all that is holy, please keep the tooling documentation in one place. It's now already spread across both the HOWTO and the new "HR label cheat sheet", which is at .../process-faq. We need to unify those, not duplicate (parts of) the instructions into yet a third place.

I don't really care what the final place is - it could all be in the DocumentReview page for all I care - but please keep it in one place.

As I said on July 2nd, there were some differences between the HOWTO and HR label cheat sheet. I'm not sure whether it will be better to merge the docs first or merge the docs as we sort the differences - but having multiple docs is a recipe for disaster PARTICULARLY while we're sorting the differences out.

  1. Also point to https://github.com/w3c/horizontal-issue-tracker for those eager WG folks who want to look at the tracker pages.
  2. Reword the prompts (and maybe change text that needs it) in https://w3c.github.io/horizontal-issue-tracker/process-faq. Probably rename it as label-faq. Replace the final section in that document, about the director, with the text in https://w3c.github.io/horizontal-issue-tracker/HOWTO under the heading "What happens to unresolved issues marked *-needs-resolution?"

The net effect of these changes is that WG folks have a single point of entry in the Guide, they can get most of the information they need from the DocumentReview page, but they can get some additional information related to label handling if they want. Horizontal review folks can start with the https://github.com/w3c/horizontal-issue-tracker and find the more specific information they need. The WG folks can, but don't need to be sidetracked by stuff that is written for the benefit of the HR groups - instead we avoid inflicting them with verbiage about non-WG related stuff.

Thoughts?

Single point of entry in/from the Guide is great, but keep the details in one place, please.

Maybe you could convince me otherwise once we have sorted out the semantic differences and understand how this is all working - but we're not there yet. Let's not have multiple sets of documents to keep in sync while we're working that out.

r12a commented 4 years ago

@samuelweiler perhaps i can calm you down a little by being a little more clear about some things.

  1. I put the process-faq into the repo mainly so that it's visible to others while we discuss what goes where, but mostly for security, because until now the latest version has been only on my laptop. The only place it is linked to is this thread, and if you hunt through the directory on the repo home page. If we decide that all that material belongs elsewhere, i will delete the file (and i plan to change the filename anyway). It's currently just a place to store information temporarily.

  2. I'm as keen as you to not replicate information in more than one place.

  3. In a previous life i was trained as and worked as a documentation writer. At that time i was taught to focus on clarifying who my audience is and making the information presented to them as relevant, concise, and well-signposted as possible. As Ivan illustrated when we discussed this on a recent call, i think we have two quite different audiences here: one is the WG personnel, and the other is the technical staff and chairs of the HR groups. The information that the WG personnel need is much simpler and shorter than that needed for the HR folks, and i don't want to deluge them with unnecessary information. That's why i'm considering the possibility of having separate entry points for each. But i repeat: I don't want to duplicate the same information in more than one place if at all possible.

So i'll make some edits along the lines described above. But before that, i'll add some text to the 'cheat sheet' file to make it clearer that it's not yet ready for consumption.

r12a commented 4 years ago

I have merged the 'cheat sheet' information into this and the DocumentReview page. I took into account @xfq 's suggestion in this PR. Therefore closing this.