prototyping-rmd-first.Rmd

# Building with RMarkdown {#proto-rmdfirst}

Once again, we advise not to directly write in the Shiny application.
We recommend using the 'Rmd first' method.  

It is important to correctly visualize the structure of your application before the build:
number of pages and elements, how the different elements interact with each other, what are the inputs needed and the outputs.
If you worked the 'UI-first', this should be clearer now.
It is then time to develop the core of the different parts of the application.  

## Define the content of the application

Put everything in Rmarkdown files.
Use the Rmarkdown files as the sandbox of your application.
If you work for a client, Rmd files knitted as HTML or PDF are easily shared for discussions about their expectations.
When there are modifications of expectations or needs to visualize different propositions, knitting a Rmd file is usually easier than manually clicking on your Shiny application to reach the modified part and take a snapshot.

Your application may contain data wrangling operations, multi-parameters based models, summary tables outputs, graphical outputs.
All this manipulations do not require the interactivity of the Shiny application to be developed.  

We propose to divide the different parts of your Shiny application into multiple Rmarkdown files where you present and develop the content.  
You may want to create one Rmarkdown file for each page / tab of the graphical interface.
The static development will simplify the multiple tests necessary during development to verify that algorithms output the correct results, to propose different colors combinations for your graphs, to improve the speed of operations, ...
You can use some dataset examples from real cases, small reproducible examples, or from fake datasets (See §\@ref(proto-tools)).


## Fill the Rmd files

Rmarkdown files are the place to write what you have in mind. 
As soon as it is related to your Shiny application of course.
Write your questions, your objectives.
Detail methods used and choices you made for your data wrangling, models, visualization.
This will help you present them to your client, boss, colleagues. 
This will also help yourself in the future when you will want to debug some parts of your code.
This will simplify discussion with other developers if you separated the work between multiple persons.  

> Note that developing in multiple Rmd files helps the allocation of work between multiple developers and will reduce code conflicts during development.

## Use the 'Rmd first' method to document further

We recommend building Shiny Apps in a package.
A package requires documentation and unit tests.
While you develop the content of your application in a series of Rmarkdown files, it is a good time to create functions. 
Indeed, the code written in the Rmarkdown will be used a second time in the Shiny application when time has come to include it.
To reduce copy-pasting, you may want to take advantage of the package structure to create functions of your code and store them in the 'R' directory of the package. 
As you write your function, write its roxygen documentation and list dependencies.
Also, because you created your code based on one or multiple examples, you are able to directly write unit tests for your newly created functions.
Writing a proper documentation and unit tests will save you a lot of time when you will implement the different functionalities in your application. 
This will often allow to detect cascading modifications of the outputs during the _check_ of the package, before you play with the graphical interface.

> The Rmd files are the vignette of the package. 
Store them in the vignette directory, so that they are built and tested when you _check_ the package.


Note that once the application is set up and functionalities included, you will surely got back to the code to debug, add new functionalities, ...
Continue to use the Rmarkdown files after the prototyping phase all along the development.