Issue for style questions/consistency

[juliasilge]

I'm hoping that we can use this issue for questions about consistency in style for the whole book.

My first one: should we show or hide code to make plots in the book? I show the code on my blog because I know some people are interested specifically in that and always ask questions, but I lean toward hiding in the book, since it is not about plotting at all. Thoughts?

[dgrtwo]

I think we should show the code for at least some plots, since I do think the ease of visualization with ggplot2 is a major benefit for the tidy text workflow. (It's something that can't be done directly from other packages)

But two ways we can reduce it:

1. We can show code for some plots but not others: for example, for the first time we show a particular kind of plot. This requires some judgment and I'm not sure about it.
2. We should find ways to hide the theme customization. The colors in your plots are awesome (I am so much lazier and rely on defaults!) but use a lot of code. What if we defined those themes in a hidden chunk beforehand? That way if someone tried the code just from the book, they'd get a decent default plot.

[juliasilge]

Yeah, maybe we can use this to make consistently themed plots in the whole book, actually. Just define/hide some nice theme customization for the whole thing.

[juliasilge]

Another question: we can put

new_session: yes

at the beginning of _bookdown.yml if we want, and that forces each .Rmd to be self-contained, I think? Then in each chapter, we would need to repeat each library(tidytext) and so forth, and also right now in the first few chapters there are dependencies on the actual data frames themselves (tidy_books, etc).

On the one hand, things might get repetitive. On the other hand, if the point is to be helpful and tutorial-like, it seems rather unhelpful to send people searching back through past chapters to find out where something was defined. I lean toward setting the new session variable to yes?

[dgrtwo]

I think that's a good idea but it means we'd have to define the aforementioned ggplot2 theme each time- even if hidden that's a lot of duplication. Perhaps we should have a setup.R that defines that, and gets called in a hidden chunk at the start of each chapter.

I think it also currently requires chunk names to be unique even among chapters, which is annoying, so if this fixes that it would be great.

[juliasilge]

Title or sentence case for chapter and section headings? I don't have a preference but we need to be consistent and the sooner we start editing these things the more likely we are to get them all right.

(Also, I don't think we need to go lower than section headings; I think we should change everything to ## that is currently ###.)

[dgrtwo]

OK, few suggested conventions, please let me know if you disagree:

• Sentence case for chapter and section headers
• Can we use two character indentation (it looks like you use eight sometimes?)
• We should give all chunks names and use explicit dependson (here is my recommended practice](https://twitter.com/drob/status/738786604731490304)): now that we're caching everything those will matter; and it's also useful when compiling to see what it's spending time on
• I think we both already follow this but let's enshrine rule of a newline per %>%

I'm not sure about ###. I think I do find subsections useful and other books like R4DS use them (see here); and we may find that there are too many sections in the table of contents otherwise

[juliasilge]

These all sound good to me. I've already started giving chunks names as I edit; I'll keep going with that.

• I do normally use 8-character indentation but I don't care too much. Two is not that many; you find that readable enough? Four maybe? Or convince me?
• Now that the TOC collapses I think that subsections make sense and look OK, and you are right. (There are examples right now of subsections that should be sections, though.)

[dgrtwo]

I used to use four spaces (broom package is an artifact of that time) but moved to two about 1.5 years ago. I've been surprised at how readable it is, and it does help avoid hitting 80 chars!

My best argument is that I think we otherwise follow all of Hadley's style guide and this would get us to 100% 😀

[juliasilge]

We might want to go through and change all the factor handling to use forcats functions; they are much nicer.

[juliasilge]

A couple of thoughts/questions...

• I think I went through and changed theme_set in everything to be the same, but in case I didn't, I am liking how theme_light looks, and I think we can just go with the default ggplot2 colors. I don't think it's at all a problem in this context that the plots are super obviously made by ggplot2.
• I have several places where I have notes to myself/us on work needing to be done, just as "TODO: blah blah blah". Should we move all of those to GitHub issues, and clear out all the TODOs within the text, for official announcement time? Some of these I don't intend to work on right now. Or is some placeholder in the text a nice communication of what is to come? I'll be honest I haven't paid too much attention to how other people have handled this when writing a book publicly.