Add a section on Introduction to .Rd files in doc chapter

[SaranjeetKaur]

Use more descriptive link text than "here", this is important for accessibility (see e.g. https://usability.yale.edu/web-accessibility/articles/links). E.g. "in the Writing R Extensions manual".

I think we should be clear that the suggested guidelines are a summary of those written for R Core developers. I think you still have the link to them (https://developer.r-project.org/Rds.html), but at the moment the connection is not clear. We should clarify this to give appropriate credit and to show that these are not just our opinion, but the recommended style.

Although that link calls them "system help files", I don't think that's a helpful description this sounds like it's related to the operating system some how. Also, we want to keep subtitles short, ideally less than 30 characters so the full sub-title can be seen in the navigation pane. So I'd rename this section "Guidelines for writing R help files"

I think you need more of an introduction to .Rd files. The point is that many R package authors use roxygen to write documentation, so will not be so familiar with this format. You don't need to duplicate the content of the R-exts manual, but it would good to give a brief overview before moving on to the guidelines. E.g. "The R help files are written in “R documentation” (Rd) format, a markup language which resembles LaTeX...". Probably you should also say where to find these files in the R sources, so that people know where to look if they want to create a patch of an R help file.

I think this intro to .Rd could go after the overview of the header/body/footer, which is a description of the help files themselves and not specific to the .Rd (or roxygen) source.

Originally posted by @hturner in #66 (comment)