WordPress.org

Making WordPress.org

Opened 5 weeks ago

Last modified 13 days ago

#5432 new task

HelpHub + GitHub integration for Google Season of Docs project

Reported by: tacitonic Owned by:
Milestone: Priority: normal
Component: General 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 (18)

#1 @tacitonic
5 weeks 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 5 weeks ago by tacitonic (previous) (diff)

#2 @dd32
5 weeks 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.


5 weeks ago

#4 @tacitonic
5 weeks 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
5 weeks ago

Hi Dion,

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

#6 @dd32
5 weeks 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
5 weeks ago

  • Priority changed from high to normal

#8 follow-up: @tacitonic
5 weeks ago

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

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

Last edited 5 weeks ago by tacitonic (previous) (diff)

#9 in reply to: ↑ 8 ; follow-up: @dd32
5 weeks 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
5 weeks 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 5 weeks ago by milana_cap (previous) (diff)

#11 follow-up: @Kenshino
5 weeks ago

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

#12 in reply to: ↑ 11 @dd32
5 weeks 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
3 weeks 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
3 weeks 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
3 weeks 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
2 weeks ago

This has the support of the Docs Team!

#17 follow-up: @coffee2code
13 days 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
13 days 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. :)

Note: See TracTickets for help on using tickets.