R package development II: documentation

This blog is Part II of the series on R package development.

It focuses on best practices for code documentation, with emphasis on quantitative development and research-oriented software systems. 

The core principles are consistency, automation, and integration into the development workflow. The recommendations are based on current documentation standards and practical lessons learned from errors, failures, improvements, and technical consultations.

The most widely recognized best practices are the following:

1. Adopt consistent style conventions: Following a clear naming flow, commenting style, block of code, templates and project structures to improves readability, reproducibility and portability.
2. Write for humans first: Comments and documentation should prioritize clarity in a plain language, and avoid unnecessary comments.
3. Be concise but informative: Aim for balance by documenting the “why” behind code decisions rather than the “what” that is evident in the syntax.
4. Use standardized tools: In R, the roxygen2 package is considered the best practice for documenting functions and packages.
5. Integrate with version control: Platforms such as GitHub encourage the inclusion of documentation alongside code commits, issues, and pull requests. 
6. Provide reproducible examples: Each documented function should include usage examples that can be directly executed.
7. Document at multiple levels: Documentation should exist at different layers:
   1. Inline comments for clarifying specific logic within functions.
   1. Function-level documentation for explaining parameters, return values, and examples.
   1. High-level project documentation (e.g., README files or vignettes) for describing goals, data sources, and workflows.
8. Keep documentation up to date: Update descriptions whenever the code changes, automated testing pipelines can even include to check this.
9. Focus on reproducibility: Especially in R, documentation should detail the computational environment, dependencies, and data sources.
10. Encourage user feedback: Documentation is a living resource. Providing avenues for users to report unclear instructions or request additional examples helps improve its quality over time.