Improve Tutorial Documentation

[simon-tarr]

Firstly, thanks to the developers for creating shiny.fluent. While I've been unable to use the library to its fullest just yet, I'm excited to begin developing with it once I've overcome some hurdles I've outlined below. I hope these comments can be viewed as constructive criticism on improving the tutorial, rather than a complaint!

I have spent some time this week going through the shiny.fluent tutorial. I'm a reasonably experienced R developer but found it difficult to follow. I think this is because there's lots of 'replace' and 'now let's just add' parts of the tutorial which do not explicitly say what users are supposed to replace or where new code chunks should be added. In addition, the lack of cumulative code blocks makes it very difficult to determine whether the user's script it on parity with the tutorial.

For example in Tutorial 1 we need to add some data to the app. However, users aren't told where to add the code to process the data. For experienced R/Shiny developers, it's reasonably straightforward to work out that this should perhaps live outside the ui and server elements, but this is not mentioned in the text. It would be possible to also wrap the data loading into a reactive within server, leading to confusion on the best place to locate this code. To the best of my knowledge, the tutorial does not link to the accompanying tutorials files so it's left to the user to attempt to work out what's supposed to go where, which is made difficult without clear instruction. Similarly, the tutorial does not explicitly say where the app's filters should live (again outside of ui and server but this is not explicitly defined; a reasonable alternative place to locate the filter code could be within ui). While most users of shiny.fluent are no doubt reasonably competent Shiny developers, I still think the tutorial would benefit greatly from being clearer for all skill levels.

I think an easy way to fix this particular issue would be to show cumulative code chunks in the tutorial, rather than just showing the new piece of code without saying where it needs to go in the script file.

Finally, in the tutorial code directory there is a script called dashboard_layout.R. In there there are multiple ui and server elements (e.g. for server here and here). Again, I was not able to find an explanation in the tutorial text as to why two server instances are defined. Is it one for each page in the dashboard? Or is this a mistake in the code?

If I pull out dashboard_layout.R into a new Shiny project--copying the www folder in the process so I have the CSS and logo--I cannot get the page to render correctly in Chrome (see screenshot below). At present, I can't figure out why. I suspect it's because of multiple ui and server elements, but I can't be sure just yet. Is anyone able to confirm whether dashboard_layout.R is fully reproducible? Or does the end user need to make some tweaks to this script in order to get the page to render correctly?

[jakubsob]

Thanks @simon-tarr!

I agree, there's definitely a room for improvement in the tutorial. We're currently mostly focused on releasing the package on CRAN to make it available for broader audience. The release will be a good opportunity for us to revisit tutorials to make sure new users have all they need to start using the package. We'll make sure to clean-up the code and make the tutorial easier to follow.

Thank you for this very thorough feedback, we highly appreciate it