Making WordPress.org

Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#6283 closed feature request (fixed)

Workflow keywords for release docs

Reported by: milana_cap's profile milana_cap Owned by: dd32's profile dd32
Milestone: Priority: normal
Component: Trac Keywords:
Cc:

Description

Currently we have 4 workflow keywords relating to docs:

  • needs-dev-note
  • has-dev-note
  • needs-codex
  • needs-docs

During release cycles these are used for marking tickets by docs focus lead/team. However, some of these are refering to past time when Codex was the main place for documentation. Today we have different structure and current keywords are confusing to people, especially newer contributors who never contributed to Codex.

We propose adding new keywords:

  • needs-devhub - developer docs
  • needs-helphub - end user docs
  • needs-field-guide - some changes are significant enough to be mentioned in Field guide but too small to have dedicated Dev note.

If it's possible to safely re-label all needs-codex to needs-helphub and all needs-docs to needs-devhub then that might be a good way to not clutter what's in use. If not, then maybe keep them so we don't lose track of all the docs tickets.

Change History (8)

#2 @dd32
2 years ago

  • Status changed from new to reopened

Can we remove the helphub and devhub from these? To prevent needing to change the tag again in future, and also to convey it to people who are unfamiliar with the WordPress project?

Last edited 2 years ago by dd32 (previous) (diff)

#3 @dd32
2 years ago

#6219 was marked as a duplicate.

#4 @dd32
2 years ago

Two relevant things from #6219:

By @atachibana:

As a member of a documentation team, the terms "devhub" and "helphub" are familiar (of course :-) ), but perhaps not so much to the average contributor.
In that case, "needs-dev-docs" or "needs-user-docs" might be better.

by me:

I think we should keep needs-docs as-is and add replace needs-codex with needs-user-docs or maybe needs-support-docs.

Due to the implementation, we can't just rename them though, we can only remove it from the UI for future ticket edit actions, it'll need to be 'manually' applied to all previous tickets in the milestone.

#5 follow-up: @milana_cap
2 years ago

Ah thank you for pointing that out. I forgot there was already a ticket.

needs-docs and needs-user-docs are good enough but also adding something for field guide would be very helpful. needs-field-guide might be misleading as it could sound like a very big feature that needs the whole field guide. Perhaps add-to-field-guide or something similar. I don't want to mess with naming conventions as long as we have keyword that indicates mentioning ticket in Field guide.


#6 @dd32
2 years ago

In 11775:

Trac: Rename needs-codex to needs-user-docs.

See #6283.

#7 in reply to: ↑ 5 @dd32
2 years ago

Replying to milana_cap:

needs-docs and needs-user-docs are good enough

Great!

but also adding something for field guide would be very helpful. needs-field-guide might be misleading as it could sound like a very big feature that needs the whole field guide.

To be honest, I didn't even know what a Field Guide was until this ticket...
Looking at the previous fieldguides, it seems to be that fieldguides are a collection of Dev Notes, but Dev Notes that have been deemed to be important enough to highlight in an end-of-cycle post? ie. Some dev notes are deemed to not be as important to be included?

Looking at the existing tickets, it doesn't look like this has been tracked in Trac at all? (ie. not through a custom keyword).

I'm not sure needs-field-guide makes sense here, as you'd not be flagging things as has-field-guide afterwards, but perhaps add-to-field-guide as you've said makes sense.

I've updated https://core.trac.wordpress.org/report/36 for the needs-codex change.

#8 @dd32
2 years ago

  • Owner set to dd32
  • Resolution set to fixed
  • Status changed from reopened to closed

In 11776:

Trac: Add a add-to-field-guide keyword for Docs team.

Props milana_cap, dd32.
Fixes #6283.

This ticket was mentioned in Slack in #docs by zzap. View the logs.


2 years ago

Note: See TracTickets for help on using tickets.