Suggest Rmd hunks approach for README&vignette?

[maelle]

cf https://www.garrickadenbuie.com/blog/dry-vignette-and-readme/

[noamross]

I'm of mixed opinion on this. It needs more real-world testing. I suggest we wait a cycle or two and see how adoption of this or other similar workflows progresses.

[maelle]

So should we even not suggest it at all in the guide? Cf phrasing in #161

[noamross]

I tweaked wording over in #161

[maelle]

Ok, I'll merge, and let this issue open. If we're lucky, by the end-of-the-year release we'll have learnt of other approaches / feedback on this approach. Many thanks @noamross!

[maelle]

Should we actively ask feedback on the approach (via the forum/Slack) or look into recent repos to see whether anyone uses the approach?

[noamross]

I'd ask if people do it, and see if there are common approaches. But I'm actually not sure this is going to have a lot of uptake, and that may be best. For instance, I think very few people use the roxygen2 tools that allow you to re-use documentation pieces, and the packages that do often have very unhelpful docs, because (1) it's nice for developers to be able to read docs in-source, and (2) you often want subtly different things in different contexts.

[maelle]

Do you know the guide also mentions that roxygen2 functionality? https://devguide.ropensci.org/building.html#documentation "If you prefer not to clutter up code with extensive documentation, place further documentation/examples in files in a man-roxygen folder in the root of your package, and those will be combined into the manual file by the use of @template , for example."

[gadenbuie]

roxygen2 templates can be particularly helpful when you have a family of functions that all operate on or return a common data type. I found @malcolmbarrett's use of templates in ymlthis to be an elegant example. His templates are also very short and have limited scope, highlighting that they're best used for specific text that you're certain won't change over time or in different function contexts.

[maelle]

Thanks, would you like to make a PR to the dev branch to add a link to this example?

[malcolmbarrett]

Thanks, @gadenbuie! I picked up a lot about templates from @alexpghayes while working on a broom PR. I think broom has a lot of powerful examples of using templates

[maelle]

I've added suggestions and mentioned the downside. Thanks everyone!