Style guide for RAs

[jstac]

Hi guys,

One value added of quantecon lectures is unified style.  We are OK at this but we could be better.

For example, in the style guide, it says "Capitalization of only first word for all other headings (sections, subsections, etc.)". 

But even the style guide doesn't follow this :-)

Nor do most of our lectures.

This issue is to track specification, recording and "compliance" with our style guide. Please feel free to add to the discussion. Let's also list tasks that need to be achieved --- and then open separate issue.

The order of operations should be

1. Discuss style guide
2. Add all changes and enhancements
3. Implement style uniformly through all lectures

I list some comments and ideas below.

[jstac]

On figure size (see https://manual.quantecon.org/writing/styleguide.html#figure-size), the manual should spell out what we need to do at the start of each lecture. It should govern ordinary figures and figures with captions. It should tell authors not to change the default figure size unless they are doing something nonstandard.

[jstac]

In the past we have used prime for transpose, as in https://python.quantecon.org/lqcontrol.html. I suggest we document and revert to this convention (which is not perfect but would be time consuming and error prone to change).

On the topic of matrices and vectors, we do not use bold face for either.

[jstac]

Regarding code, I suggest the following:

Our convention is to follow PEP8 unless there is a good reason to do otherwise. One good reason is to get closer to mathematical notation in a given lecture. Hence it's fine to use capitals for matrices, etc.

Operators are typically surrounded by spaces, as in a * b and a + b, but we write a**b for $a^b$.

[HumphreyYang]

On figure size (see https://manual.quantecon.org/writing/styleguide.html#figure-size), the manual should spell out what we need to do at the start of each lecture. It should govern ordinary figures and figures with captions. It should tell authors not to change the default figure size unless they are doing something nonstandard.

Just to add to the style of figure captions and labels, one thing @jstac mentioned to me in our meeting this week is that the axis labels and labels in the legend should not be capitalized unless they are proper names like GDP.

[jstac]

Thanks @HumphreyYang .

This is motivated by the following rule of thumb: keep everything as simple and plain as possible, conditional on not generating ambiguity.

For captions on figures, let's capitalize the first letter (e.g., "Output as a function of price"). As @HumphreyYang says, labels shouldn't be capitalized unless they are proper nouns.

Figure captions should be constrained to around five or six words.

[jstac]

An issue related to style: Until now, all exercises have been pushed to the end of each lecture.

Now we have nice exercise environments with hidden (dropdown) solutions, I suggest we permit mixing them through the lecture. In many cases this is more natural, since we want to reinforce a point by requesting students do an exercise before proceeding.

[shlff]

Thanks @jstac and @HumphreyYang .

For rule number 2 of https://manual.quantecon.org/writing/styleguide.html#plotting-figures, should we attach a link to jupyter-book docs on how to add a caption to figure directive or code-cell metadata and how to refer to it? For example, here

• https://jupyterbook.org/en/stable/reference/cheatsheet.html?highlight=numref#figures-and-images
• https://jupyterbook.org/en/stable/reference/cheatsheet.html?highlight=numref#referencing-figures

(Btw, the wordstitle caption seem redundant.)

[mmcky]

Thanks @jstac I think this is a great time to review the style guide and thanks for kicking this discussion off.

I'll do a detailed pass of the style guide today to address some of the points above.

I think we should also refactor it to stand alone in the manual as its own part to promote it as a primary reference.

Style Guide
  - Writing Conventions
  - Figures and Images
  - Code
  - References
  - Index

this will also give some more space for showing examples without the page getting really long.

then change current Writing Lectures to Writing Workflows

I think they are all great ideas to add to it.

It should tell authors not to change the default figure size unless they are doing something nonstandard.

In our projects we will cycle through and define a default image size in _config.yml (otherwise the default image size is variable given matplotlib returns variably sized images. So we should link a seealso to to the updated global configuration page

It is exciting the manual is becoming a central point of reference and resource for the organisation.

[jstac]

Thanks @mmcky , very helpful and I agree with all of these suggestions

[shlff]

Thanks @mmcky and @jstac .

Also wondering whether it would be of help to add a part briefly discussing how to add exercises and solutions with the exercise-solution environment and its limitations on using other syntax together.

[jstac]

Good idea, thanks @shlff

@mmcky , perhaps you could ask @shlff or @HengchengZhang to cross-check this issue and the refactored style document to make sure no points raised above get missed?

[jstac]

For figures generated by matplotlib within lectures, do we want to standardize on captioned figures, as in

---
mystnb:
    figure: xxx
---

I'm wondering if this would give a more uniform look, help people reference figures by numbering them, and also allow us to get rid of plt.rcParams['figure.figsize'] = (10,6) at the top of each lecture, which is a bit unattractive and error-prone.

[mmcky]

@HengchengZhang and @shlff I have refactored the style guide and made a first pass on incorporating the updates from this issue.

• [x] move to new style guide part
• [x] refactor page into chapters
• [x] incorporate https://github.com/QuantEcon/meta/issues/88 (first pass)

These changes have now been merged and are available on the main branch and changes are live on https://manual.quantecon.org/intro.html. It would be great if you could please review and submit PR's with any corrections / edits or suggestions.

[mmcky]

• [x] @mmcky to incorporate exercises and proofs

[mmcky]

With https://github.com/QuantEcon/QuantEcon.manual/pull/24 I think this can be closed @jstac.

Perhaps we should do a final review to make sure all your points of included in the updated style guide?