From c83945969b63fe7bdd6dae1f9a9ef3ffa3548025 Mon Sep 17 00:00:00 2001 From: cjrace <52536248+cjrace@users.noreply.github.com> Date: Wed, 9 Oct 2024 10:07:24 +0100 Subject: [PATCH 01/11] Copy sjaffa's changes from #183 and add examples of successfully closed bugs --- 01-Introduction.Rmd | 10 ++--- 08-documenting.Rmd | 102 ++++++++++++++++++++++++-------------------- 2 files changed, 61 insertions(+), 51 deletions(-) diff --git a/01-Introduction.Rmd b/01-Introduction.Rmd index 8925179d..98cd18ac 100644 --- a/01-Introduction.Rmd +++ b/01-Introduction.Rmd @@ -9,11 +9,12 @@ Contributions to base R are possible in a number of different ways. Some of them 1. Contributing to bug fixing: Refer [Bug Tracking](#BugTrack) and [Reviewing Bugs](#ReviewBugs). 2. Contributing to translations: Refer [Translations](#). 3. Testing R before release: Refer [Testing Pre-release R Versions](#TestRVer). - - +4. Contributing to documentation and tutorials, including this guide: Refer [Documenting R](#Doc) and [Contributing to this guide](#how-to-contribute-to-this-guide). +Maintainers and contributors are requested to follow this project's [code of conduct](https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md). + ## Quick start to the guide The guide is intended as a comprehensive resource for contributing to base R. The following chapter outline provides an overview with links to sections for getting started with contributing. @@ -42,11 +43,10 @@ The guide is intended as a comprehensive resource for contributing to base R. Th ## How to contribute to this guide itself? {#how-to-contribute-to-this-guide} +All contributors should start by reading the [contributing page for this project](https://github.com/r-devel/rdevguide/blob/main/CONTRIBUTING.md). + This guide is built using bookdown which makes editing it easier, provided you have a GitHub account (sign-up at [github.com](https://github.com/)). After you log-in to GitHub, click on the ‘Edit’ icon highlighted with a red ellipse in the image below. This will take you to an editable version of the the source R Markdown file that generated the page you are on: ![Screenshot of the toolbar in the HTML version of the guide, with the Edit button (pencil and paper icon) circled in red.](img/edit_icon.png) Use the [issue tracker](https://github.com/r-devel/rdevguide/issues) to raise an issue about the guide’s content or to make a feature request. - -Maintainers and contributors are requested to follow this project's [code of conduct](https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md). - diff --git a/08-documenting.Rmd b/08-documenting.Rmd index 1ac23d68..b8a9705e 100644 --- a/08-documenting.Rmd +++ b/08-documenting.Rmd @@ -4,7 +4,60 @@ R has a substantial body of documentation, comprising help files for the core pa The involvement of the community takes many forms, from contributing content, to making bug reports or raising an issue when the documentation could be more complete or made easier to follow. -This chapter is about the ways people can contribute to R's documentation, with guidance on how to do that. Any time you feel that you can clarify or fill gaps in existing documentation, your contribution is welcome and appreciated. If you find it difficult to deal with the markup used in the source files, you can ask for help with that part too. Please do not let the material in this chapter stand between the documentation and your desire to help out. However, not every good faith effort to change or extend the documentation will be accepted - sometimes the suggested changes may be incorrect; other times, while a change in wording may make some things clearer and easier to understand, the finer details of some corner case may become less clear, leading to the suggested changes being declined or modified by a member of R Core before applying them (if they agree the issue is important enough to fix). +This chapter is about the ways people can contribute to R's documentation, with guidance on how to do that. Any time you feel that you can clarify or fill gaps in existing documentation, your contribution is welcome and appreciated. If you find it difficult to deal with the markup formatting language used in the source files, you can ask for help with that part too. Please do not let the material in this chapter stand between the documentation and your desire to help out. However, not every good faith effort to change or extend the documentation will be accepted - sometimes the suggested changes may be incorrect; other times, while a change in wording may make some things clearer and easier to understand, the finer details of some corner case may become less clear, leading to the suggested changes being declined or modified by a member of R Core before applying them (if they agree the issue is important enough to fix). + +## Helping with documentation + +Maintaining the accuracy of R's documentations and keeping a high level of quality takes a lot of effort. Community members, like you, help with writing, editing, and updating content, and these contributions are appreciated and welcomed. + +Looking at pre-existing documentation source files can be very helpful when getting started. + +You can directly search for [documentation issues/bugs on Bugzilla](https://bugs.r-project.org/buglist.cgi?component=Documentation&list_id=22501&product=R&resolution=---). Issues vary from typos to unclear documentation and items lacking documentation. + +If you see a documentation issue that you would like to tackle, you can leave a comment on the issue saying you are going to try to solve the issue and mention roughly how long you think you will take to do so (this allows others to take on the issue if you happen to forget or lose interest). + +## Reporting documentation bugs + + +If you find some typo or problem on the [CRAN](https://cran.r-project.org) webpages you can write a polite email to `CRAN@r-project.org` to report it. As an alternative, one can also write to the R-devel mailing list or submit a bug report via R's Bugzilla. + +For improvements of the R-manuals or reporting typos or bugs in the R-manuals, submit a bug report to [R's Bugzilla](https://bugs.r-project.org/). + +For reporting bugs or typos on the webpages or documentation about a particular package, write to the corresponding package maintainer. To find the maintainer of a package, use the command `maintainer("package-name")`. + +**Note**: + +There is a `#core-documentation` channel on the [R Contributors slack](https://r-contributors.slack.com/) where you can discuss about the patches for improvements to R's documentation. + +### Example documentation bugs + +Here are a couple of successfully resolved bugs as examples. + +1. [Bug 16003 - heatmap scale argument: description not complete](https://bugs.r-project.org/show_bug.cgi?id=16003) + +There was a question about the description in the documentation, where it wasn't technically incorrect, but was slightly unclear. This led to a discussion around the updates to the text and a couple of extra examples were added in for clarity too. + +2. [Bug 18781 - typo in texinfo](https://bugs.r-project.org/show_bug.cgi?id=18781) + +This is an example of a typo being spotted, raised and fixed within the same day. + +## Guidelines for writing R help files + +This section is based on the [guidelines used by R Core developers for writing R help files](https://developer.r-project.org/Rds.html). Extensive details of writing R documentation files can be found in the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) manual. + +The language used in the documentations should follow these basic rules: + +1. Affirmative tone should be used to describe what the function does and how to use it effectively. Rather than creating worry in the mind of a reader, it should establish confident knowledge about the effective use of the particular function/feature. + +2. More documentation is not necessarily better documentation. Long descriptions full of corner cases and caveats can create the impression that a function is more complex or harder to use than it actually is. Be succinct but exhaustive. + +3. Short code examples can help in understanding better. Readers can often grasp a simple example more quickly than they can digest a formal description. Usually people learn faster with concrete, motivating examples that match the context of a typical use case. + +4. Giving a code equivalent (or approximate equivalent) can be a useful addition to the description provided. You should carefully weigh whether the code equivalent adds value to the document. + +5. The tone of the documentation needs to be respectful of the reader's background. Lay out the relevant information, show motivating use cases, provide glossary links, and do your best to connect-the-dots. The documentation is meant for newcomers, many of whom will be using it to evaluate the R language as a whole. The experience needs to be positive and not leave the reader with worries that something bad will happen if they make a mistake. ## Introduction to `.Rd` files @@ -113,22 +166,6 @@ c(xm, mean(x, trim = 0.10)) Many R package developers write help files using the R package [roxygen2](https://cran.r-project.org/package=roxygen2), which generates `.Rd` files from comments in the corresponding `.R` files. However, in this guide we only consider `.Rd` files, because the help files for the base distribution are written and edited directly in `.Rd` format. -## Guidelines for writing R help files - -This section is based on the [guidelines used by R Core developers for writing R help files](https://developer.r-project.org/Rds.html). Extensive details of writing R documentation files can be found in the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) manual. - -The language used in the documentations should follow these basic rules: - -1. Affirmative tone should be used to describe what the function does and how to use it effectively. Rather than creating worry in the mind of a reader, it should establish confident knowledge about the effective use of the particular function/feature. - -2. More documentation is not necessarily better documentation. Long descriptions full of corner cases and caveats can create the impression that a function is more complex or harder to use than it actually is. Be succinct but exhaustive. - -3. Short code examples can help in understanding better. Readers can often grasp a simple example more quickly than they can digest a formal description. Usually people learn faster with concrete, motivating examples that match the context of a typical use case. - -4. Giving a code equivalent (or approximate equivalent) can be a useful addition to the description provided. You should carefully weigh whether the code equivalent adds value to the document. - -5. The tone of the documentation needs to be respectful of the reader’s background. Lay out the relevant information, show motivating use cases, provide glossary links, and do your best to connect-the-dots. The documentation is meant for newcomers, many of whom will be using it to evaluate the R language as a whole. The experience needs to be positive and not leave the reader with worries that something bad will happen if they make a mistake. - ## R manuals The [R manuals](https://cran.r-project.org/manuals.html) are a part of the [R sources](https://svn.r-project.org/R/trunk/doc/manual/). Hence, bug reports/patches can also be submitted via Bugzilla, e.g. [Bug 15221 - R-admin/'Installing R under Windows': Missing argument name](https://bugs.r-project.org/bugzilla/show_bug.cgi?id=15221). Note that they are typically referred to by their file names as listed below: @@ -148,18 +185,6 @@ Note: - The [R manuals](https://cran.r-project.org/manuals.html) page has links for the [three types of release](https://contributor.r-project.org/rdevguide/GetStart.html#the-r-source-code): `r-release`, `r-patched` and `r-devel`. These nicknames appear in the URLs, e.g. https://cran.r-project.org/doc/manuals/r-release/R-intro.html. - The [Texinfo manual](https://www.gnu.org/software/texinfo/) should be referred to for [how to mark up text](https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html). -## Helping with documentation - -Maintaining the accuracy of R's documentations and keeping a high level of quality takes a lot of effort. Community members, like you, help with writing, editing, and updating content, and these contributions are appreciated and welcomed. - -Looking at pre-existing documentation source files can be very helpful when getting started. - -You can directly search for [documentation issues/bugs on Bugzilla](https://bugs.r-project.org/buglist.cgi?component=Documentation&list_id=22501&product=R&resolution=---). Issues vary from typos to unclear documentation and items lacking documentation. - -If you see a documentation issue that you would like to tackle, you can leave a comment on the issue saying you are going to try to solve the issue and mention roughly how long you think you will take to do so (this allows others to take on the issue if you happen to forget or lose interest). - -If you find some typo or problem on [CRAN](https://cran.r-project.org) after checking the problem or typo you can write a polite email to `cran-sysadmin@r-project.org` and one of the R-core members working with CRAN. You'll probably get a prompt reply about how the issue is going to be fixed. - ## Proofreading While an issue filed on Bugzilla means there is a known issue somewhere, that does not mean there are not other issues lurking about in the documentation. Proofreading a part of the documentation can often uncover problems. @@ -168,24 +193,9 @@ If you decide to proofread, read a section of the documentation from start to fi ## Helping with the Developer's Guide -The Developer’s Guide (what you are reading now) uses the same process as the main R documentation, except for some small differences. The source lives in a [GitHub repository](https://github.com/r-devel/rdevguide/) and bug reports should be submitted to the [devguide GitHub tracker](https://github.com/r-devel/rdevguide/issues). - -Our dev guide workflow uses continuous integration and deployment so changes to the dev guide are normally published when the pull request is merged. [How to contribute to this guide from the introduction.](#how-to-contribute-to-this-guide) - -## Reporting documentation bugs - - -If you find some typo or problem on the [CRAN](https://cran.r-project.org) webpages you can write a polite email to `CRAN@r-project.org` to report it. As an alternative, one can also write to the R-devel mailing list or submit a bug report via R's Bugzilla. - -For improvements of the R-manuals or reporting typos or bugs in the R-manuals, submit a bug report to R's Bugzilla. +The Developer's Guide (what you are reading now) uses the same process as the main R documentation, except for some small differences. The source lives in a [GitHub repository](https://github.com/r-devel/rdevguide/) and bug reports should be submitted to the [devguide GitHub tracker](https://github.com/r-devel/rdevguide/issues). -For reporting bugs or typos on the webpages or documentation about a particular package, write to the corresponding package maintainer. To find the maintainer of a package, use the command `maintainer("package-name")`. - -**Note**: - -There is a `#core-documentation` channel on the [R Contributors slack](https://r-contributors.slack.com/) where you can discuss about the patches for improvements to R's documentation. +Our Developer's Guide workflow uses continuous integration and deployment so changes to the Developer’s Guide are normally published when the pull request is merged. [How to contribute to this guide from the introduction.](#how-to-contribute-to-this-guide) ## See also From 138b3c00de4a77ecf102b34775115dd00b04fc12 Mon Sep 17 00:00:00 2001 From: cjrace <52536248+cjrace@users.noreply.github.com> Date: Wed, 9 Oct 2024 10:30:09 +0100 Subject: [PATCH 02/11] Respond to original PR comment and add a note that documentation tends to be a good starting place --- 01-Introduction.Rmd | 3 +++ 1 file changed, 3 insertions(+) diff --git a/01-Introduction.Rmd b/01-Introduction.Rmd index 98cd18ac..2fa467b4 100644 --- a/01-Introduction.Rmd +++ b/01-Introduction.Rmd @@ -10,9 +10,12 @@ Contributions to base R are possible in a number of different ways. Some of them 2. Contributing to translations: Refer [Translations](#). 3. Testing R before release: Refer [Testing Pre-release R Versions](#TestRVer). 4. Contributing to documentation and tutorials, including this guide: Refer [Documenting R](#Doc) and [Contributing to this guide](#how-to-contribute-to-this-guide). + +A common starting point for new contributors is to start with documentation, as this allows for an easier way into the ways of working and tools used. + Maintainers and contributors are requested to follow this project's [code of conduct](https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md). ## Quick start to the guide From 4237b7815f06915cbda5f804a5c96ba53f15c409 Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 10:20:30 +0000 Subject: [PATCH 03/11] Commit PR suggestion from hturner Co-authored-by: Heather Turner --- 01-Introduction.Rmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/01-Introduction.Rmd b/01-Introduction.Rmd index 2fa467b4..8d901c89 100644 --- a/01-Introduction.Rmd +++ b/01-Introduction.Rmd @@ -6,9 +6,9 @@ This guide is a comprehensive resource for contributing to base R^[The [set of p Contributions to base R are possible in a number of different ways. Some of them are listed below: -1. Contributing to bug fixing: Refer [Bug Tracking](#BugTrack) and [Reviewing Bugs](#ReviewBugs). -2. Contributing to translations: Refer [Translations](#). -3. Testing R before release: Refer [Testing Pre-release R Versions](#TestRVer). +1. Contributing to bug fixing: Refer to [Issue Tracking](#IssueTrack) and [Reviewing Bugs](#ReviewBugs). +2. Contributing to translations: Refer to [Translations](#message-translations). +3. Testing R before release: Refer to [Testing Pre-release R Versions](#TestRVer). 4. Contributing to documentation and tutorials, including this guide: Refer [Documenting R](#Doc) and [Contributing to this guide](#how-to-contribute-to-this-guide). From 3c3bc864f18725019676fb0200c7f156e42b7477 Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 10:20:44 +0000 Subject: [PATCH 04/11] Commit PR suggestion from hturner Co-authored-by: Heather Turner --- 01-Introduction.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/01-Introduction.Rmd b/01-Introduction.Rmd index 8d901c89..e28d0b04 100644 --- a/01-Introduction.Rmd +++ b/01-Introduction.Rmd @@ -9,7 +9,7 @@ Contributions to base R are possible in a number of different ways. Some of them 1. Contributing to bug fixing: Refer to [Issue Tracking](#IssueTrack) and [Reviewing Bugs](#ReviewBugs). 2. Contributing to translations: Refer to [Translations](#message-translations). 3. Testing R before release: Refer to [Testing Pre-release R Versions](#TestRVer). -4. Contributing to documentation and tutorials, including this guide: Refer [Documenting R](#Doc) and [Contributing to this guide](#how-to-contribute-to-this-guide). +4. Contributing to documentation, including this guide: Refer to [Documenting R](#Doc) and [Contributing to this guide](#how-to-contribute-to-this-guide). From 4cf05ca153c9a7fc5c8a36c854095dce95711d47 Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 10:21:23 +0000 Subject: [PATCH 05/11] Commit PR suggestion from hturner Co-authored-by: Heather Turner --- 01-Introduction.Rmd | 1 - 1 file changed, 1 deletion(-) diff --git a/01-Introduction.Rmd b/01-Introduction.Rmd index e28d0b04..a9a1052c 100644 --- a/01-Introduction.Rmd +++ b/01-Introduction.Rmd @@ -14,7 +14,6 @@ Contributions to base R are possible in a number of different ways. Some of them -A common starting point for new contributors is to start with documentation, as this allows for an easier way into the ways of working and tools used. Maintainers and contributors are requested to follow this project's [code of conduct](https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md). From 88a9b75c0ca6a8764b4b8722b9878ddfc30a97a5 Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 10:24:22 +0000 Subject: [PATCH 06/11] Commit PR suggestion from hturner Co-authored-by: Heather Turner --- 08-documenting.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/08-documenting.Rmd b/08-documenting.Rmd index b8a9705e..fd9f32d0 100644 --- a/08-documenting.Rmd +++ b/08-documenting.Rmd @@ -8,7 +8,7 @@ This chapter is about the ways people can contribute to R's documentation, with ## Helping with documentation -Maintaining the accuracy of R's documentations and keeping a high level of quality takes a lot of effort. Community members, like you, help with writing, editing, and updating content, and these contributions are appreciated and welcomed. +Maintaining the accuracy of R's documentation and keeping a high level of quality takes a lot of effort. Community members, like you, help with writing, editing, and updating content, and these contributions are appreciated and welcomed. Looking at pre-existing documentation source files can be very helpful when getting started. From 659fd0cc4b6a9580bfec739dc74d9162f479b3f1 Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 10:24:40 +0000 Subject: [PATCH 07/11] Commit PR suggestion from hturner Co-authored-by: Heather Turner --- 08-documenting.Rmd | 1 - 1 file changed, 1 deletion(-) diff --git a/08-documenting.Rmd b/08-documenting.Rmd index fd9f32d0..f1d38d25 100644 --- a/08-documenting.Rmd +++ b/08-documenting.Rmd @@ -21,7 +21,6 @@ If you see a documentation issue that you would like to tackle, you can leave a discussion in slack (random channel) --> -If you find some typo or problem on the [CRAN](https://cran.r-project.org) webpages you can write a polite email to `CRAN@r-project.org` to report it. As an alternative, one can also write to the R-devel mailing list or submit a bug report via R's Bugzilla. For improvements of the R-manuals or reporting typos or bugs in the R-manuals, submit a bug report to [R's Bugzilla](https://bugs.r-project.org/). From 2005281125f2dcfd49bec1e3e10f71bb7cad257c Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 10:24:55 +0000 Subject: [PATCH 08/11] Commit PR suggestion from hturner Co-authored-by: Heather Turner --- 08-documenting.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/08-documenting.Rmd b/08-documenting.Rmd index f1d38d25..1c650838 100644 --- a/08-documenting.Rmd +++ b/08-documenting.Rmd @@ -28,7 +28,7 @@ For reporting bugs or typos on the webpages or documentation about a particular **Note**: -There is a `#core-documentation` channel on the [R Contributors slack](https://r-contributors.slack.com/) where you can discuss about the patches for improvements to R's documentation. +There is a `#core-documentation` channel on the [R Contributors slack](https://r-contributors.slack.com/) where you can get feedback before reporting an issue or get feedback on proposed improvements. ### Example documentation bugs From 03cfa5fb7a9eac7eac518d51682b2779a0f644d7 Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 10:25:57 +0000 Subject: [PATCH 09/11] Commit PR suggestion from hturner Co-authored-by: Heather Turner --- 08-documenting.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/08-documenting.Rmd b/08-documenting.Rmd index 1c650838..783d8be1 100644 --- a/08-documenting.Rmd +++ b/08-documenting.Rmd @@ -192,7 +192,7 @@ If you decide to proofread, read a section of the documentation from start to fi ## Helping with the Developer's Guide -The Developer's Guide (what you are reading now) uses the same process as the main R documentation, except for some small differences. The source lives in a [GitHub repository](https://github.com/r-devel/rdevguide/) and bug reports should be submitted to the [devguide GitHub tracker](https://github.com/r-devel/rdevguide/issues). +Contributions to the R Development Guide (what you are reading now) are also welcome. The source for this guide lives in a [GitHub repository](https://github.com/r-devel/rdevguide/) and bug reports should be submitted to the [issue tracker](https://github.com/r-devel/rdevguide/issues). Our Developer's Guide workflow uses continuous integration and deployment so changes to the Developer’s Guide are normally published when the pull request is merged. [How to contribute to this guide from the introduction.](#how-to-contribute-to-this-guide) From 6c2116ab2ebf2a5be6e82f4b74ea179f6178546d Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 11:30:30 +0000 Subject: [PATCH 10/11] Changes to introduction and contributing to this guide based on PR comments --- 01-Introduction.Rmd | 5 ++--- 08-documenting.Rmd | 9 +++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/01-Introduction.Rmd b/01-Introduction.Rmd index a9a1052c..21f52130 100644 --- a/01-Introduction.Rmd +++ b/01-Introduction.Rmd @@ -14,9 +14,6 @@ Contributions to base R are possible in a number of different ways. Some of them - -Maintainers and contributors are requested to follow this project's [code of conduct](https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md). - ## Quick start to the guide The guide is intended as a comprehensive resource for contributing to base R. The following chapter outline provides an overview with links to sections for getting started with contributing. @@ -47,6 +44,8 @@ The guide is intended as a comprehensive resource for contributing to base R. Th All contributors should start by reading the [contributing page for this project](https://github.com/r-devel/rdevguide/blob/main/CONTRIBUTING.md). +Maintainers and contributors are also requested to follow [this guide's code of conduct](https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md). + This guide is built using bookdown which makes editing it easier, provided you have a GitHub account (sign-up at [github.com](https://github.com/)). After you log-in to GitHub, click on the ‘Edit’ icon highlighted with a red ellipse in the image below. This will take you to an editable version of the the source R Markdown file that generated the page you are on: ![Screenshot of the toolbar in the HTML version of the guide, with the Edit button (pencil and paper icon) circled in red.](img/edit_icon.png) diff --git a/08-documenting.Rmd b/08-documenting.Rmd index 783d8be1..935765f9 100644 --- a/08-documenting.Rmd +++ b/08-documenting.Rmd @@ -21,10 +21,9 @@ If you see a documentation issue that you would like to tackle, you can leave a discussion in slack (random channel) --> +For improvements of the R-manuals, reporting typos or bugs in the R-manuals, or issues related to packages maintained by the R core team, read the [reporting bugs guide](#ReportBug). -For improvements of the R-manuals or reporting typos or bugs in the R-manuals, submit a bug report to [R's Bugzilla](https://bugs.r-project.org/). - -For reporting bugs or typos on the webpages or documentation about a particular package, write to the corresponding package maintainer. To find the maintainer of a package, use the command `maintainer("package-name")`. +For reporting bugs or typos on webpages or documentation about a particular package where it is not maintained by the R core team, you can find the maintainer of a package by using the `maintainer("package-name")` function. **Note**: @@ -194,7 +193,9 @@ If you decide to proofread, read a section of the documentation from start to fi Contributions to the R Development Guide (what you are reading now) are also welcome. The source for this guide lives in a [GitHub repository](https://github.com/r-devel/rdevguide/) and bug reports should be submitted to the [issue tracker](https://github.com/r-devel/rdevguide/issues). -Our Developer's Guide workflow uses continuous integration and deployment so changes to the Developer’s Guide are normally published when the pull request is merged. [How to contribute to this guide from the introduction.](#how-to-contribute-to-this-guide) +There's a section on the introduction page detailing [how to contribute to this guide](#how-to-contribute-to-this-guide). Once you have made suggested changes you can raise them for someone else to review through a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) on GitHub. Examples of past pull requests can be found on the [pull request tab in this guide's GitHub repository](https://github.com/r-devel/rdevguide/pulls?q=is%3Apr+is%3Aclosed). + +Our Developer's Guide workflow uses continuous integration and deployment so changes to the live Developer’s Guide site are normally published once a pull request is merged. ## See also From 6b51fc688b2f550bd9b80b9bbd1df1f57aeb4bf0 Mon Sep 17 00:00:00 2001 From: Cam Race <52536248+cjrace@users.noreply.github.com> Date: Wed, 4 Dec 2024 14:35:01 +0000 Subject: [PATCH 11/11] Apply suggestions from code review Co-authored-by: Heather Turner --- 09-documenting.Rmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/09-documenting.Rmd b/09-documenting.Rmd index 4b26580f..15ae7b45 100644 --- a/09-documenting.Rmd +++ b/09-documenting.Rmd @@ -21,9 +21,9 @@ If you see a documentation issue that you would like to tackle, you can leave a discussion in slack (random channel) --> -For improvements of the R-manuals, reporting typos or bugs in the R-manuals, or issues related to packages maintained by the R core team, read the [reporting bugs guide](#ReportBug). +To suggest improvements to the R manuals, report typos or bugs in the R manuals, or to raise issues related to documentation in packages maintained by the R Core Team, follow the usual guidance for [reporting bugs in R](#RCorePkgBug). -For reporting bugs or typos on webpages or documentation about a particular package where it is not maintained by the R core team, you can find the maintainer of a package by using the `maintainer("package-name")` function. +To report bugs or typos in the documentation of a package that is not maintained by the R Core Team, follow the guidance for [reporting bugs in contributed packages](#nonRCorePkgBug). **Note**: @@ -194,7 +194,7 @@ If you decide to proofread, read a section of the documentation from start to fi The R Development Guide (what you are reading now) uses the same process as the main R documentation, except for some small differences. The source lives in a [GitHub repository](https://github.com/r-devel/rdevguide/) and bug reports should be submitted to the [devguide GitHub tracker](https://github.com/r-devel/rdevguide/issues). There's a section on the introduction page detailing [how to contribute to this guide](#how-to-contribute-to-this-guide). Once you have made suggested changes you can raise them for someone else to review through a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) on GitHub. Examples of past pull requests can be found on the [pull request tab in this guide's GitHub repository](https://github.com/r-devel/rdevguide/pulls?q=is%3Apr+is%3Aclosed). -Our Developer's Guide workflow uses continuous integration and deployment so changes to the live Developer’s Guide site are normally published once a pull request is merged. +Our workflow for the R Development Guide uses continuous integration and deployment so changes to the live R Development Guide site are normally published once a pull request is merged. ## See also