Add paragraph on avoiding overlap between package website and CRAN package vignettes

[vincentvanhees]

Hello, I would like to propose a new paragraph to discourage duplication of vignettes between CRAN vignettes (if package is on CRAN) and package website.

Background on why I propose this: For a package that I maintain we have elaborate documentation in CRAN vignettes (link). They have evolved over the years and are the key resource for the package users. However, as you know, the limitation of CRAN vignettes is that they cannot be updated without having to make an entire new package release. Therefore, I am now transitioning to having a package website (with pkgdown) that hosts most of the documentation complemented by CRAN vignettes that are only brief and that reference the website. I think that using the same vignette for the website would be confusing since it is then unclear what the real latest documentation is given that both are not updated simultaneously. Most likely the CRAN vignettes will always run behind with the package website. But even if both would be identical then it still looks messy to have two locations for the same information. So, I think the best solution is to discourage duplication of information between CRAN and website, and to have a link from CRAN to website.

Note: As this is a small update I did not create an issue.

[noamross]

Thank you for your input @vincentvanhees! We'll give this one a think. I appreciate your concern about diverging versions. On the other hand, CRAN vignettes are some of the most visible documentation, which also are installed with the package and automatically built in many other contexts, and I'd be loathe to reduce the quality of that resource. With documentation you often do want redundancy and maximum visibility, in having as full documentation as possible available in multiple locations, including the website and CRAN.

[vincentvanhees]

Thanks, I see your point. An alternative solution could be to encourage a statement in each vignette that warns the reader that the CRAN instance of the vignette reflects the latest CRAN release of the package and may not be identical to the website instance of the vignette which reflects the latest GitHub instance of the package.

[mpadge]

Thanks @vincentvanhees, but again i concur with Noam here. I further note that many authors (myself included) generally ensure that updates to pkgdown vignettes are reflected in updated CRAN versions as soon as possible, so lags between versions are not an issue for many authors. It is also very important to note that internal package vignettes are the only version guaranteed to be available to all users at all times, because they can always be viewed offline. These are also always published by both CRAN and rOpenSci, and so duplication is unavoidable.

Given that, I'll close this PR for now, but please don't let that discourage you, and feel free to continue to help us to improve our documentation.

[vincentvanhees]

Thanks, just to clarify that I made these comments with my own repository in mind that has been having monthly GitHub releases for years and where I intentionally only submit a new CRAN release 3 or 4 times per year in order to not burden the CRAN team with my frequent updates. As a result, my GitHub codebase is typically months ahead of the latest CRAN release. CRAN has been automating their package release process by which I think I can now start increasing the release frequency on CRAN and by that aim for more consistency with GitHub. In conclusion, my concerns are not as relevant and generically applicable as I thought they were. Thanks for taking the time to reply and to challenge my suggestion.

[mpadge]

No worries, and again: please feel free to help us in the future by suggesting any improvements you see fit. Thanks for the insights nonetheless!