Skip to content

Create a friendlier system of project documentation#15337

Merged
seanbudd merged 20 commits into
masterfrom
splitReadme
Sep 3, 2023
Merged

Create a friendlier system of project documentation#15337
seanbudd merged 20 commits into
masterfrom
splitReadme

Conversation

@seanbudd

@seanbudd seanbudd commented Aug 28, 2023 •
edited
Loading

Copy link
Copy Markdown
Member

Summary of the issue:

There are a few issues with the current project documentation:

  • The README is quite long, and focused largely on configuring the developer environment.
    Instead, it should be a homepage for the various aspects of the project. Detailed information should be split into their own documents.
  • contributing.md is quite long and should be split similarly into the ways one can contribute to NVDA.
  • There is a lot of missing information in terms of how to get started with various ways of contributing.

Description of user facing changes

README.md is now split into

  • Community information
    • support / getting help
    • getting add-ons
    • Issue reporting
    • General community information

Contributing.md is now split into

  • testing
  • translating
  • Issue triage
  • Development
    • Design
  • add-on dev
    • add-on distribution

Guides have been updated or added when missing.

Known issues with pull request:

None

Change log entries:

For Developers
The NVDA project documentation has been updated...

@seanbudd seanbudd marked this pull request as ready for review August 28, 2023 06:02
@seanbudd seanbudd requested a review from a team as a code owner August 28, 2023 06:02
@seanbudd

seanbudd commented Aug 28, 2023

Copy link
Copy Markdown
Member Author

this is now ready for review

@seanbudd seanbudd requested a review from Qchristensen August 28, 2023 06:29
michaelDCurran
michaelDCurran requested changes Aug 28, 2023
View reviewed changes
Comment thread projectDocs/testing/contributing.md Outdated
Comment thread projectDocs/testing/contributing.md Outdated
seanbudd
seanbudd commented Aug 28, 2023
View reviewed changes
Comment thread projectDocs/dev/buildingNVDA.md Outdated
Comment thread projectDocs/dev/buildingNVDA.md Outdated
Comment thread projectDocs/dev/contributing.md Outdated
@seanbudd @michaelDCurran
Apply suggestions from code review
4e72b5d 
Co-authored-by: Michael Curran <mick@nvaccess.org>
@seanbudd seanbudd added the conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review. label Aug 28, 2023
Qchristensen
Qchristensen approved these changes Aug 30, 2023
View reviewed changes

@Qchristensen Qchristensen left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great job on this, thank you.

@seanbudd seanbudd requested a review from a team as a code owner August 30, 2023 04:10
seanbudd
seanbudd commented Aug 30, 2023
View reviewed changes
Comment thread projectDocs/community/readme.md Outdated
@seanbudd

seanbudd commented Aug 30, 2023 •
edited
Loading

Copy link
Copy Markdown
Member Author

Community feedback would be great here!
This is a big change, so feedback on structure as well as content would be welcome.
We'd like to make the content as accessible, logically compiled and easy to navigate as possible.

It might be easier to review the documents directly:

We've also updated the wiki home page to include a clearer contents index and migrated content from the other wiki repository nvda-community

@AppVeyorBot

This comment was marked as outdated.

Sign in to view
@nvdaes

nvdaes commented Aug 31, 2023

Copy link
Copy Markdown
Collaborator

In Community readme, I wonder if the community add-ons website should be mentioned in addition to the store:

  • Personally, I'm not sure about if it's well maintained.
    • Imo, downloading add-ons from the store itself is more secure than installing them from external sources when possible, since checsum is used to ensure that releases are inmutable and that, when an add-on installed, the manifest contains NVDA API versions.
      Then, if the community website is mentioned, I suggest to add a brief note about differences between the store and the website, for example: add-on store (recommended) or something.

@seanbudd

seanbudd commented Aug 31, 2023

Copy link
Copy Markdown
Member Author

The community add-ons website is still being supported by NV Access for now, and is the source of some add-ons that aren't available from the add-on store.

I agree that it's probably worth a note that this website is towards end of life and the add-on store is preferred

@AppVeyorBot

AppVeyorBot commented Sep 1, 2023

Copy link
Copy Markdown

See test results for failed build of commit f0c2ac5817

nvdaes
nvdaes suggested changes Sep 1, 2023
View reviewed changes
Comment thread projectDocs/community/readme.md
@nvdaes

nvdaes commented Sep 1, 2023

Copy link
Copy Markdown
Collaborator

Imo, maybe useful to inform what channels are supported by NV Access. Sometimes we, community members, may say that our website, mailing list or whatever resource is official, without clarifying the meaning of the "official" word. So I sugest to inform people what channels are supported by NV Access.

@seanbudd

seanbudd commented Sep 3, 2023

Copy link
Copy Markdown
Member Author

@nvdaes -I've added some subheaders to indicate this

@seanbudd seanbudd merged commit 59d59bb into master Sep 3, 2023
@seanbudd seanbudd deleted the splitReadme branch September 3, 2023 23:47
@nvaccessAuto nvaccessAuto added this to the 2023.3 milestone Sep 3, 2023
@seanbudd seanbudd mentioned this pull request Sep 4, 2023
Merged
seanbudd added a commit that referenced this pull request Sep 4, 2023
@seanbudd
Update codeowners (#15360)
1f2504b 
Follow up to #15337

Summary of the issue:
Update CODEOWNERS to cover project documentation.
Request a review from our documentation reviewers (Quentin) when modifying relevant project documentation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Qchristensen Qchristensen Qchristensen approved these changes

@michaelDCurran michaelDCurran Awaiting requested review from michaelDCurran

+1 more reviewer

@nvdaes nvdaes nvdaes requested changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review.

Projects

None yet

Milestone

2023.3

Development

Successfully merging this pull request may close these issues.

6 participants

@seanbudd @AppVeyorBot @nvdaes @michaelDCurran @Qchristensen @nvaccessAuto