Skip to content

STYLE_GUIDE.md

Latest commit

 

History

History
114 lines (86 loc) · 4.94 KB

STYLE_GUIDE.md

File metadata and controls

114 lines (86 loc) · 4.94 KB

Style guide

In general

  • Be precise, clear, engaging, pragmatic, and consistent

Text

Use warm, inclusive language (such as “them”, even when referring to a single person). Stick to simple language, as many of the readers/contributors may not be native English speakers. You could leverage tools like Grammarly to help with spelling and grammar checks.

  • Chapters and Sections
    • Provide an overview at the beginning of each chapter.
    • Be consistent in the structure of each section.
      • ## Your turn! 🚀 for exercises/assignments.
      • ## Self study for further reading resources.
      • ## Acknowledgments if needed.
      • add bibliography by using the JupyterBook built-in way.
    • Only capitalize the first letter.
  • Don't add the URL as plain text. Instead, add it as a preview.
  • Quotes - use double quotes
  • Symbol descriptions - timestep t（not t timestep）
  • Use numerals when they are explaining or part of code or math.
  • Acceptable abbreviations
    • AI, MLP, CNN, RNN, GRU, LSTM, model names (e.g., ELMo, GPT, BERT)
    • We spell out full names in some cases to be clear (e.g., NLP -> natural language processing)

Math

  • Be consistent in math notation
  • Place punctuations within equations if necessary
    • e.g., comma and period
  • Assignment symbol
    • \leftarrow
  • Use mathematical numerals only when they are part of math: "$x$ is either $1$ or $-1$", "the greatest common divisor of $12$ and $18$ is $6$".
  • We do not use "thousands separator" (since different publishing houses have different styles). E.g., 10,000 should be written as 10000 in the source markdown files.

Figure

  • Software
    • draw.io, add/edit the .draw.io file in the ./drawio folder.
    • Follow this for mermaid, wavedrom, plantuml, tikz, blockdiag.
    • Add inline quiz.
  • Be careful about COPYRIGHT. Add the reference inline by using the markdown figure format.
  • Always add the link to the original source.
  • Style(optional)
    • Size：
      • Horizontal：<= 400 pixels (limited by page width)
      • Vertical：<= 200 pixels (exceptions may be made)
    • Thickness：
      • StickArrow
      • 1pt
      • arrowhead size: 50%
    • Font：
      • Arial (for text), STIXGeneral (for math), 9pt（subscripts/superscripts：6pt）
      • Do not italicize numbers or parentheses in subscripts or superscripts
    • Color：
      • Blue as background (text is black)
        • (Try to avoid) Extra Dark：3FA3FD
        • Dark：66BFFF
        • Light：B2D9FF
        • (Try to avoid) Extra Light: CFF4FF

Code

Data

If sample data is needed for the book or assignments, first try to use built-in ones from sklearn or tensorflow if possible.

To introduce your own dataset, put the data file into the ./asserts/data folder, then it could be referred to by a relative path. You can also add Python code, binary, and any other type of static asserts.

Slides

The project's slide source code is hosted in open-machine-learning-jupyter-book/slides/. If you want to add or edit any slide, please refer to the demo and example code here. The slideshow functionality is powered by reveal.js, and you could find the detailed documentation there.

References

Citations

  1. Use zoterobib to generate consistent keys for bibtex entries. Please keep the format to be consistent with zoterobib if you prefer any other bib management tools.

  2. Add the bibtex entry to references.bib on the root directory. Such as below,

@article{wood2011sequence,
  title={The sequence memoizer},
  author={Wood, Frank and Gasthaus, Jan and Archambeau, C{\'e}dric and James, Lancelot and Teh, Yee Whye},
  journal={Communications of the ACM},
  volume={54},
  number={2},
  pages={91--98},
  year={2011},
  publisher={ACM}
}
  1. In the text, use the following to cite the added paper:
{cite}`Wood.Gasthaus.Archambeau.ea.2011`

Appendix

Acknowledgments

Inspired by d2l-ai.