Tweaks to business cycle lecture

[jstac]

Excellent work on this lecture @HumphreyYang

Rather than using titles embedded in matplotlib figures, could we please switch to numbered figures using numref (see, e.g., the inequality lecture).

Captions should use a capital for the first word and for any proper nouns, but not for other nouns (@mmcky , should we add this to the manual / style file?)

Captions should be relatively short --- max of around five words. A fuller description can appear in the text.

Also, please tidy up and perhaps hide a little more code. Many people will read this lecture for the figures and content. Once they want to explore and reproduce, they can click to open code cells.

Code should respect PEP8 as much as possible --- 80 character lines, for example.

Cut words in text as much as possible without changing the meaning:

Examples:

• "becoming more and more" -> "becoming more"
• "we also need to acknowledge that the" -> "the"
• "is often very different" -> "often differs".
• " to better understand and reflect on" -> "better understand"
• "We find that the real output of the industry is also highly" -> "Industrial output is also"
• "credit level expands rapidly in the period of economic expansion" -> "credit increases during economic expansions"

Perhaps @maanasee would be willing to do this last part?

[HumphreyYang]

Many thanks for these suggestions @jstac.

One thing I noticed is that figures in the inequality lecture have two titles:

Should I follow the same convention?

(Also, I am not sure whether the embedded title and caption are improvements over the title in matplotlib in terms of the style; as in matplotlib titles, we have more control over the style)

[jstac]

Thanks @HumphreyYang , good point and I appreciate you raising it.

I agree with you on the style --- the current caption style is not suitable --- but I've asked @mmcky to address this so we should have a nicer style on captions soon.

Also, having more control can be a problem because we end up with lots of different styles :-)

As a rule, let's move to

1. elminating all titles in matplotlib (no ax.set_title...)
2. replacing them with captions in numbered figures
3. Using lower case for captions, except for the first letter (and proper nouns)
4. Keeping the captions down to about 5~6 words max

We will end up with a nice uniform style and numbered figures so we can more easily refer to them.

For figures that don't really need a caption, it's fine to omit it.

Perhaps these rules could be added to the style file?

CC @HengchengZhang @mmcky @shlff

[jstac]

Hi guys, let's keep this moving forward. Please let me know if you need my input.

@HengchengZhang @mmcky @shlff please give a thumbs up to the last comment after you read it.

[jstac]

@mmcky , would you mind to add these style suggestions to the style manual?

[mmcky]

@jstac these are some nice rules and additions for the style guide. I will update that now with these ideas for plotting.

These rules work really well for figures that are generated by code and enables the captions to be edited more freely. The main tradeoff is if the figure is ever turned into a static asset it isn't always clear how to keep track of the metadata associated with it -- so we need to be careful to transfer it to a figure along with the associated metadata as well (i.e. captions etc.) but worth it with the additional control and embedded look and feel relative to having that metadata embodied by matplotlib.

[mmcky]

re: theme upgrade. I have included this in this months planned 0.5.0 release of the quantecon-book-theme along with https://github.com/QuantEcon/quantecon-book-theme/milestone/6

The status of work is available on our priorities dashboard.

https://github.com/orgs/QuantEcon/projects/1/views/1

(cc @AakashGfude)

[jstac]

The main tradeoff is if the figure is ever turned into a static asset it isn't always clear how to keep track of the metadata associated with it

I think our priority should be to avoid static assets.

[mmcky]

@jstac here is the updated style guide page

https://manual.quantecon.org/writing/styleguide.html#plotting-figures

I have added a fifth rule re: name for use with numref

[mmcky]

The main tradeoff is if the figure is ever turned into a static asset it isn't always clear how to keep track of the metadata associated with it

I think our priority should be to avoid static assets.

OK I have now added this point as a guiding principle admonition

https://manual.quantecon.org/writing/styleguide.html#plotting-figures

[jstac]

Thanks @mmcky , good to have that documented.

[jstac]

I think we can close this now but please reopen if I missed something.