R Language Meta: Documentation Guidelines Making good examples
Example
Most of the guidance for creating good examples for Q&A carries over into the documentation.
-
Make it minimal and get to the point. Complications and digressions are counterproductive.
-
Include both working code and prose explaining it. Neither one is sufficient on its own.
-
Don't rely on external sources for data. Generate data or use the datasets library if possible:
library(help = "datasets")
There are some additional considerations in the context of Docs:
-
Refer to built-in docs like
?data.framewhenever relevant. The SO Docs are not an attempt to replace the built-in docs. It is important to make sure new R users know that the built-in docs exist as well as how to find them. -
Move content that applies to multiple examples to the Remarks section.
