Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

WIP: Improve documentation on how to contribute to documentation #183

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

WIP: Improve documentation on how to contribute to documentation #183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
280e10b
Add suggestion to improve documentation
SJaffa Sep 5, 2024
2526e4b
Add link to contributing to this guide
SJaffa Sep 5, 2024
4d97267
Make Code of Conduct note more prominent
SJaffa Sep 5, 2024
f0c03ec
Explain what markup means
SJaffa Sep 5, 2024
26a9787
Change order of sections to group different kinds of docs
SJaffa Sep 5, 2024
5c1e644
Remove extra space and avoid jargon
SJaffa Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions 01-Introduction.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,13 @@ 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).

<!-- TODO(Saranjeet): Refer Contributing to R tutorial -->
<!-- TODO(Saranjeet): Welcome to Bug BBQ slides -->
<!-- TODO(Saranjeet): README on Bug BBQ repo -->

Maintainers and contributors are requested to follow this project's [code of conduct](https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md).
Copy link
Author

Choose a reason for hiding this comment

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

This change is not directly related to my aim of helping people contribute to docs, but in reading as a new contributor I found I clicked away on links before getting to this important statement at the end of the page, so it may be better to put it higher up to ensure people are aware fo the CoC before they go into the details of how to contribute.


## 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.
Expand Down Expand Up @@ -47,6 +49,3 @@ This guide is built using bookdown which makes editing it easier, provided you h
![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).

90 changes: 45 additions & 45 deletions 08-documenting.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,50 @@ 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).

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 `[email protected]` 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.
Copy link
Member

Choose a reason for hiding this comment

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

In line 26 (next paragraph) the email suggested is different. I think [email protected] is the right one.


## Reporting documentation bugs
<!---
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 `[email protected]` 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.

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.

## 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

Expand Down Expand Up @@ -113,22 +156,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:
Expand All @@ -148,18 +175,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 `[email protected]` 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.
Expand All @@ -170,22 +185,7 @@ If you decide to proofread, read a section of the documentation from start to fi

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
<!---
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 `[email protected]` 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.

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

Expand Down