search

rstudio / shiny

Easy interactive web applications with R
http://shiny.rstudio.com
Other
5.3k stars 1.87k forks source link

Documentation: devmode docs need some improvement #4082

Open daattali opened 1 month ago

daattali commented 1 month ago

Since devmode is continuing to get new features, it might be worthwhile to make sure it's easy to understand so that its usage isn't suffered.

  1. The documentation for devmode opens with:

    Developer Mode enables a number of [options()](https://rdrr.io/r/base/options.html) to make a developer's life easier, like enabling 
non-minified JS and printing messages about deprecated functions and options.

    This does not tell me what are all the options that get set with devmode. I could not find anywhere a clearly defined list of options that are affected by devmode.

  2. It might be obvious, but I think it's important to still note that devmode should only be used while developing/testing and not in production

  3. I assume that the vast majority of shiny users and devmode users are creating shiny apps rather than creating shiny packages. The majority of the documentation page for devmode is dealing with functions and concepts that are only relevant for package authors. This adds a lot of noise and clutter for shiny developers who are just trying to understand how they can use devmode. As a shiny app developer, when I look at the list of functions on that page, it's a lot to take in and can cause me to give up.

  4. The documentation was for the verbose parameter is "Logical value which should be set to TRUE display" - it's missing a word

  5. The explanation for the devmode() function is: "Function to set two options to enable/disable Shiny Developer Mode and Developer messages". I found this confusing. I thought this is referring to the two options mentioned at the top of the docs - minifying JS and printing messages. The part that's confusing is that it mentions "two options" - that's getting into the detail of what the function is literally doing, but it's ambiguous because setting the devmode option causes other options to get enabled. Therefore, I think that language should be avoided, and it should just say "Enable/disable Shiny Developer Mode and Developer messages"

  6. There's a lot of inconsistent terminology used for the messaging. "Shiny Developer messages", "Developer Mode message", "Developer messages". Choose one way to call it and stick with it to make it clear that it's talking about the same thing in all these instances.

  7. I find it unintuitive that calling devmode() does not give deterministic results. Calling devmode() in a new session causes devmode to turn on. If I then call devmode(F), it turns devmode off - all this makes sense. But if I then call devmode() again, it doesn't turn it back on. This is the part that is strange. I understand it's because it's looking at the existing option, but that's exactly what I find strange. Calling in_devmode() should look at the existing option, it's weird to me that the devmode() argument is using the option that it sets as its default.

  8. The docs for ?shinyOptions say this about devmode:

    shiny.devmode (defaults to NULL)
    Option to enable Shiny Developer Mode. When set, different default getOption(key) values will be returned.

    It looks like the option is a boolean, and most other shiny options that are booleans have a default of either TRUE or FALSE. Is there a reason why this is defaulting to NULL rather than FALSE, like all other options? Also, the sentence "different default getOption(key) values will be returned" is an awkward unclear sentence.