Update code guide and move from wiki into manage repo space

[mcking65]

Resolve #3060 by:

1. Making recommended updates to the guide
2. Moving the guide page out of wiki to ... (TBD location)

Preview links

• Preview option 1: Code Guide | APG | WAI | W3C
• Preview option 2: aria-practices/docs/code-guide.md

---

WAI Preview Link (Last built on Sun, 11 Aug 2024 01:13:34 GMT).

[mcking65]

@OliverHabersetzer @a11ydoer @howard-e @jugglinmike ... any other interested persons ...

When discussing #3060 in last Tuesday's meeting, I had proposed we both update the content and move the guide out of wiki so we can manage changes with pull requests. During the meeting, I proposed moving the code guide into the "About" section of the APG. Another option would be to move it into a docs directory in the repository. I don't know which is better. In this PR, I set up both options.

Option 1: Move to about section

• Pro: more visible I'm not sure this is a valuable advantage because code contributors need to read the readme anyway.
• Pro: The site template automatically builds a page contents with all level 2 headings.
• Con: Requires conversion to HTML, which is kinda ugly for code snippets.

Option 2: Move to docs directory

• Pro: Can keep as markdown, which might be easier to maintain since it doesn't require linking to any ARIA specs.
• Con: ???

Which way do people think we should go with this?

[OliverHabersetzer]

Thanks a Lot. Ill start work on this on monday!

…

________________________________ From: Matt King ***@***.***> Sent: Sunday, August 11, 2024 3:23:34 AM To: w3c/aria-practices ***@***.***> Cc: Habersetzer, Oliver ***@***.***>; Assign ***@***.***> Subject: Re: [w3c/aria-practices] Update code guide and move from wiki into manage repo space (PR #3092) You don't often get email from ***@***.*** Learn why this is important<https://aka.ms/LearnAboutSenderIdentification> Assigned #3092<#3092> to @OliverHabersetzer<https://github.com/OliverHabersetzer>. — Reply to this email directly, view it on GitHub<#3092 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BJGK3QPTWN4AYKJKGDP47VLZQ24JNAVCNFSM6AAAAABMKI3NJ6VHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJTHAZTANRSGUYTCNA>. You are receiving this because you were assigned.Message ID: ***@***.***>

[nschonni]

As an alternate, this content is often put into https://github.com/w3c/aria-practices/blob/main/CONTRIBUTING.md, but that can get awkward if the guide gets too large.

[mcking65]

@nschonni wrote:

As an alternate, this content is often put into https://github.com/w3c/aria-practices/blob/main/CONTRIBUTING.md, but that can get awkward if the guide gets too large.

The guide is large. I also think it is a good idea have separate URIs for the two different kinds of info. The contributing page is related to licensing and copyrights for all contributors, not just code contributions.

[nschonni]

The contributing page is related to licensing and copyrights for all contributors, not just code contributions.

I don't find the W3C CONTRIBUTION.md as the normal format for projects. The file is intended to tell people how to contribute ideas or code to a repository. The GitHub docs cover that a little https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

Another example, where external pages are used https://github.com/nodejs/node/blob/main/CONTRIBUTING.md

[howard-e]

Option 1: Move to about section

• Pro: more visible I'm not sure this is a valuable advantage because code contributors need to read the readme anyway.
• Pro: The site template automatically builds a page contents with all level 2 headings.
• Con: Requires conversion to HTML, which is kinda ugly for code snippets.

Option 2: Move to docs directory

• Pro: Can keep as markdown, which might be easier to maintain since it doesn't require linking to any ARIA specs.
• Con: ???

Which way do people think we should go with this?

My preference is option 2, mainly because of a potential con to option 1. It being a part of the about page may be misconstrued as a strong suggestion to APG consumers on the style of how they should be implementing work in their respective codebases. That could open "unwanted" feedback on the code guide when being an authority on that doesn't seem to be the APG intends. At least according to the code guide currently.

Standards for developing contributing HTML, CSS, and JavaScript to W3C WAI-ARIA APG.

It feels more commonplace to me for someone to view the CONTRIBUTING.md, which would have link to the code guide already a part of the repo as well, before starting their PR changes.

[mcking65]

Thank you @nschonni and @howard-e for the feedback.

I agree with the points about why it is better to go for option 2. I removed the code-guide.html file from the content/about section.

[nschonni]

Unless this ends up targetting the web and needs it, the HTML should probably be removed. I think it's all fine with plain Markdown syntax

[OliverHabersetzer]

Just to give you some updates on the PR: my legal team asked me to wait before actually contributing my changes until they made their decision. Sorry for letting you wait.