Skip to content

Latest commit

 

History

History
109 lines (83 loc) · 4.41 KB

STYLE_GUIDE.md

File metadata and controls

109 lines (83 loc) · 4.41 KB
Raw

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 ./data folder, then it could be referred by a relative path.

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.