-
Notifications
You must be signed in to change notification settings - Fork 5
Spec Editing Process
In order to actively participate, you'll need to be added to the eBraille GitHub project. To get access, first make a GitHub account if you don't have one already. Then, email Avneesh your GitHub username or email and he will give you the access that you need.
To propose a change to the spec, first open an issue in GitHub. If you are unsure of how to open an issue, you can use this link to open a new issue.
It is very important that you are as specific as possible when describing and labeling your issue. What document are you wanting to change? For instance, is it the Tagging Best Practices document or the CSS Best Practices document? Specify the document in the body of your issue and add the appropriate label. For any ticket related to editing a document that is a part of the specification, add the "spec editing" label. Then add the label that specifies which document you are wanting to edit, so "tagging" for the tagging best practices document, "metadata" for the metadata best practices document, and "css" for the css best practices document. This will make it easier for us to search either by document or by spec editing generally.
Once you've made it clear which document you want to edit, then you need to be clear on what part of that document you want to edit. Copy the relevant section of text from the spec you want to edit and paste it into the ticket. Use formatting or text to make it clear which section has been copied.
Now state what is the change you want to make. For a simple change, it could be useful to just state the change you would like to see. For example, you could want to propose that "centered" be a tag for h1s in the tagging best practices document, so you could quote the section that concerns the tags for h1s under headings and then state that you would like "centered" to be added to the list of reserved classes in this section. For a more complex change, if possible, please propose the new text you would like to replace the text you previously quoted. So this would mean potentially pasting the text a second time and then making the edits to that second instance.
Finally, please state why you would like to make this change. Be as clear and specific as possible in stating your reasoning.
Once a change is proposed, it is important that we discuss the change. There's two ways to do this discussion. One is to reply to the issue and state why you agree or disagree. This process should be straightforward.
The other is to simply "react" to the proposal. If you would just like to agree with the proposal, there's an "add or remove reactions button" that is after the text of the issue in the tab order- visually it looks like a tiny line drawing of a smiling face. Use this to add a thumbs up reaction when you agree. In basic tests with NVDA, this appears to be accessible but alert the group if you have issues. Don't use reactions when you disagree as a disagreement should be accompanied with your reasoning.
Once sufficient discussion has occurred, editors will either make the proposed changes in the actual spec document and close the issue with a comment that the change was made or reply that it seems the consensus is moving against the change and close the issue without adding the changes. The amount of discussion needed about the issue will vary based on how complicated and impactful the change being proposed. A typo, for instance, will probably require no discussion. Just make a ticket and an editor will make the change. A change that greatly changes the approach of the current spec will likely require a lot of consensus.
Every effort will be made to make sure ideas are sufficiently discussed and consensus is reached. We also need to proceed at a decent pace, so please get your comments in as soon as you can. If you don't comment or react, we won't know what you're thinking.