HelpHub + GitHub integration for Google Season of Docs project

[tacitonic]

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.

[tacitonic]

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

[dd32]

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.

[tacitonic]

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.

[milana_cap]

Hi Dion,

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

[dd32]

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.

[tacitonic]

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

Never mind, I can change the settings - it updated late.

[dd32]

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.

[milana_cap]

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

[Kenshino]

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

[dd32]

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.

[tacitonic]

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.)

[dd32]

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.

[tacitonic]

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.

[Kenshino]

This has the support of the Docs Team!

[coffee2code]

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.

[tacitonic]

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. :)

[Clorith]

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

[tellyworth]

What are the next steps here?

[milana_cap]

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.

[coffee2code]

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).