WordPress.org

Making WordPress.org

Opened 13 months ago

Closed 7 months ago

#5432 closed task (fixed)

HelpHub + GitHub integration for Google Season of Docs project

Reported by: tacitonic Owned by: coffee2code
Milestone: Priority: high
Component: Handbooks Keywords:
Cc:

Description

As a part of Google's Season of Docs, I will be writing a Unified Style Guide for WordPress. It would be great to get an idea of the final product as I work. I discussed with the docs team to have a similar integration as https://developer.wordpress.org/block-editor/ - where the GitHub repo is mirrored to make.wordpress.org HelpHub or Docs.

Change History (31)

#1 @tacitonic
13 months ago

Discussion in the #docs channel: https://wordpress.slack.com/archives/C02RP4WU5/p1600097379254900
Discussion in the #meta channel: https://wordpress.slack.com/archives/C02QB8GMM/p1598863237003000
Currently working via: https://github.com/zzap/WordPress-Documentation-Style-Guide
CC: @kenshino @milana_cap @felipeelia

Last edited 13 months ago by tacitonic (previous) (diff)

#2 @dd32
13 months ago

Hi,

Is a new repo wanted, or do you want to transfer https://github.com/zzap/WordPress-Documentation-Style-Guide over?

Who requires write access to it?

Where on developer.wordpress.org should the content be mirrored to, should that be setup now or later down the line?

If you want to transfer it over, the easiest way is to transfer it to me dd32 and I'll then push it into the Organisation.
If you want a new repo, just let me know the name.

This ticket was mentioned in Slack in #meta by tacitonic. View the logs.


13 months ago

#4 @tacitonic
13 months ago

  • Component changed from HelpHub to General

Hi @dd32,
I want to transfer https://github.com/zzap/WordPress-Documentation-Style-Guide to WordPress' GitHub - as I've already started my work on that repo.

Write access would be needed by @milana_cap, @felipeelia and I.

The location hasn't been decided yet. Multiple locations were proposed in the meeting yesterday; https://make.wordpress.org/docs https://wordpress.org/support or perhaps a seperate handbook.
If it is possible, I'm open to have mirroring setup now.

Thanks for the help.

#5 @milana_cap
13 months ago

Hi Dion,

I have transferred repo to your GitHub account. Thank you for the help.

#6 @dd32
13 months ago

Migrated to https://github.com/WordPress/WordPress-Documentation-Style-Guide

Once a final location on WordPress.org is decided for the content, and it's in a state that can be imported, we'll set it up at that point in time.

There's some limitations in the markdown importer, which we can resolve at that point in time. It might be worth reviewing https://github.com/WordPress/gutenberg/tree/master/docs and the manifest which specifies how the content is imported as an example.

#7 @dd32
13 months ago

  • Priority changed from high to normal

#8 follow-up: @tacitonic
13 months ago

Thank you @dd32. Is there any way I could access the repo settings?

Version 0, edited 13 months ago by tacitonic (next)

#9 in reply to: ↑ 8 ; follow-up: @dd32
13 months ago

Replying to tacitonic:

Is there any way I could access the repo settings?

You've got Maintain access, let me know if there's any settings you specifically need changed, I'm not familiar with the project so I'm unsure of what access is actually needed here.

#10 in reply to: ↑ 9 @milana_cap
13 months ago

Replying to dd32:

You've got Maintain access, let me know if there's any settings you specifically need changed, I'm not familiar with the project so I'm unsure of what access is actually needed here.

Hi @dd32 ,

It would be great if you could add @tacitonic and @felipeelia to WordPress organisation so I can add them to the team: https://github.com/orgs/WordPress/teams/documentation-style-guide/

https://github.com/felipeelia
https://github.com/tacitonic

Thank you

Last edited 13 months ago by milana_cap (previous) (diff)

#11 follow-up: @Kenshino
13 months ago

Hello, can I please be added as an admin to the repo too?

#12 in reply to: ↑ 11 @dd32
13 months ago

Replying to milana_cap:

It would be great if you could add @tacitonic and @felipeelia to WordPress organisation so I can add them to the team: https://github.com/orgs/WordPress/teams/documentation-style-guide/

Added them to the team, pending invite.

Replying to Kenshino:

Hello, can I please be added as an admin to the repo too?

You've got access via the above team.

#13 follow-up: @tacitonic
13 months ago

Hi @dd32, the Docs team has come to a decision for the location of the Style Guide. We have decided https://make.wordpress.org/docs/style-guide as the location. What would be the process of getting this URL, but have nothing on it? (i.e. no pages or articles on the link.)

#14 in reply to: ↑ 13 ; follow-up: @dd32
13 months ago

Replying to tacitonic:

the Docs team has come to a decision for the location of the Style Guide. We have decided https://make.wordpress.org/docs/style-guide as the location. What would be the process of getting this URL, but have nothing on it? (i.e. no pages or articles on the link.)

A handbook can be setup at that location when there's content ready to go on it.

There's two methods for Handbooks on WordPress.org:

  • Automatic imports from GitHub
  • Written from within WordPress

Setting up a handbook for either is not a problem, but it's one or the other.

#15 in reply to: ↑ 14 @tacitonic
13 months ago

Replying to dd32:

A handbook can be setup at that location when there's content ready to go on it.

There's two methods for Handbooks on WordPress.org:

  • Automatic imports from GitHub
  • Written from within WordPress

Setting up a handbook for either is not a problem, but it's one or the other.

All content that would go in the handbook, would be there on the repo. https://github.com/WordPress/WordPress-Documentation-Style-Guide

So implementing automatic imports from GitHub would be the best choice.

#16 @Kenshino
13 months ago

This has the support of the Docs Team!

#17 follow-up: @coffee2code
12 months ago

As part of #5247, I was in the midst of updating the Handbooks plugin to incorporate Markdown importing, which will streamline both that ticket and this. I had to backburner it to work on other stuff, but I believe it was most of the way there. I'll see about trying to get it ready soon.

In the meantime, there are a few documents that will need to be added to the Style Guide repo before it can get imported:

  • Create manifest.json
  • Create index.md as main landing page (seems like the content in 1-introduction/1-wordpress-style-guide.md would serve this purpose)
  • Create 1-introduction/README.md
  • Create 2-document-guidelines/README.md
  • Create 3-language-and-grammar/README.md

Presuming the current directory structure implies the page hierarchy (and how the sidebar menu would be laid out), then the referenced README.md files would be the intro pages. For example, clicking "Document Guidelines" would load then 3-language-and-grammar/README.md contents, and that menu item would expand with links to child pages "Abbreviations", "Articles", "Capitalizations", etc.

I'll propose a manifest.json shortly, but creating the suggestd .md files would be of help.

#18 in reply to: ↑ 17 @tacitonic
12 months ago

Replying to coffee2code:

Thanks for working on this @coffee2code. I have created index.md as the main landing page. Additionally, I've also created the 1-introduction/README.md, 2-document-guidelines/README.md, and 3-language-and-grammar/README.md files in the repo.
Kindly let me know if there is anything else to add. :)

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


9 months ago

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


9 months ago

#21 @Clorith
8 months ago

  • Priority changed from normal to high

Bumping priority of this ticket as per docs teams prioritizing for the upcoming meta-doc-focus-session

This ticket was mentioned in Slack in #meta by clorith. View the logs.


8 months ago

#23 @tellyworth
8 months ago

  • Owner set to coffee2code
  • Status changed from new to reviewing

#24 @tellyworth
8 months ago

What are the next steps here?

#25 @tellyworth
8 months ago

  • Component changed from General to HelpHub

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


8 months ago

This ticket was mentioned in Slack in #meta by tacitonic. View the logs.


8 months ago

#28 @milana_cap
8 months ago

Hello @tellyworth ,

This, actually, has nothing to do with HelpHub. This is general Docs Style Guide and we need its repository (https://github.com/WordPress/WordPress-Documentation-Style-Guide) to be parsed into WordPress. The place for it is Make Docs so the landing URL should be https://make.wordpress.org/docs/style-guide/

Thank you.

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


8 months ago

#30 @tellyworth
8 months ago

  • Component changed from HelpHub to Handbooks

#31 @coffee2code
7 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

Following up to report this has been implemented.

The Documentation Style Guide was first imported on March 2nd. However, auto-import was only just enabled now while some kinks got worked out. (It had been manually re-imported a few times in-between.)

There were a number of Handbooks plugin updates and WPorg Markdown plugin updates that needed to happen to accommodate this (all of which were in the works anyhow).

Note: See TracTickets for help on using tickets.