- Be clear, engaging, pragmatic, and consistent
- Chapters and Sections
- Provide an overview at the beginning of each chapter
- Be consistent in the structure of each section
- Summary
- Exercises
- Quotes
- Use double quotes
- Symbol Descriptions
- timestep t(not t timestep)
- Tools, Class, and Functions
- Gluon, MXNet, NumPy, spaCy, NDArray, Symbol, Block, HybridBlock, ResNet-18, Fashion-MNIST, matplotlib
- Consider these as words without accents (``)
- Sequential class/instance, HybridSequential class/instance
- Without accents (``)
backward
function- not
backward()
function
- not
- for-loop
- Gluon, MXNet, NumPy, spaCy, NDArray, Symbol, Block, HybridBlock, ResNet-18, Fashion-MNIST, matplotlib
- Terminologies
- Consistently use
- function (not method)
- instance (not object)
- weight, bias, label
- model training, model prediction (model inference)
- training/testing/validation dataset
- data point (preferred)/data instance/training example/testing example/example of the dataset
- Distinguish:
- hyperparameter vs parameter
- minibatch stochastic gradient descent vs stochastic gradient descent
- List
- Consistently use
- Use numerals when they are explaining or part of code or math.
- Acceptable abbreviations
- MLP, CNN, RNN, GRU, LSTM, model names (e.g., ELMo, GPT, BERT)
- We spell out full names in most cases to be clear (e.g., NLP -> natural language processing)
- 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$ ".
- Software
- Use OmniGraffle to make figures.
- Export pdf (infinite canvas) in 100%, then use pdf2svg to convert to svg
ls *.pdf | while read f; do pdf2svg $f ${f%.pdf}.svg; done
- Do not export svg directly from Omnigraffle (font size may slightly change)
- Export pdf (infinite canvas) in 100%, then use pdf2svg to convert to svg
- Use OmniGraffle to make figures.
- Style
- Size:
- Horizontal:<= 400 pixels (limited by page width)
- Vertical:<= 200 pixels (exceptions may be made)
- Thickness:
- StickArrow
- 1pt
- arrow head 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
- Blue as background (text is black)
- Size:
- Be careful about copyright
- matplotlib
- Each line must have <=78 characters (limited by page width)
- Python
- To save space, put several assignments on the same line
- e.g,
num_epochs, lr = 5, 0.1
- e.g,
- Be consistent in variable names
num_epochs
- number of epochs
num_hiddens
- number of hidden units
num_inputs
- number of inputs
num_outputs
- number of outputs
net
- model
lr
- learning rate
acc
- accuracy
- During iterations
- features:
X
- labels:
y
,y_hat
orY
,Y_hat
for X, y in data_iter
- features:
- Data sets:
- features:
features
orimages
- labels:
labels
- DataLoader instance:
train_iter
,test_iter
,data_iter
- features:
- Comments
- No period at the end of comments.
- For clarity, surround variable names with accents, e.g., # shape of
X
- imports
- import alphabetically
from mxnet.gluon import data as gdata, loss as gloss, nn, utils as gutils
- Print outputs
epoch, lr, loss, train acc, time
- Around 5 lines
- Print variables
- if possible use
x, y
instead ofprint('x:', x, 'y:', y)
at the end of the code block
- if possible use
- String
- Use single quotes
- Use f-strings. To break a long f-string into multi-lines, just use one f-string per line.
- Other items
nd.f(x)
→x.nd
random_normal
→random.normal
- multiple imports
.1
→1.0
-
- →
1.0
- →
- remove namescope
- Refer to d2lbook on how to add references for figure, table and equations.
- https://www.the-qrcode-generator.com/
- 75pixel, SVG
- Run
pip install git+https://github.com/d2l-ai/d2l-book
- Use bibtool to generate consistent keys for bibtex entries. Install it by
brew install bib-tool
- Add an bibtex entry to
d2l.bib
on the root directory. Say the original entry is
@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}
}
- Run
bibtool -s -f "%3n(author).%d(year)" d2l.bib -o d2l.bib
. Now the added entry will have consistent keys. And as a side-effect, it'll appear in alphabetically sorted order relative to all other papers in the file:
@Article{ Wood.Gasthaus.Archambeau.ea.2011,
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}
}
- In the text, use the following to cite the added paper:
:cite:`Wood.Gasthaus.Archambeau.ea.2011`
- Say we want to edit and test MXNet code in xx.md, run
d2lbook activate default xx.md
. Then code of other frameworks is deactivated in xx.md. - Open xx.md using Jupyter notebook, edit code and use "Kernel -> Restart & Run All" to test code.
- Run
d2lbook activate all xx.md
to re-activate code of all the frameworks. Then git push.
Likewise, d2lbook activate pytorch/tensorflow xx.md
will only activate PyTorch/TensorFlow code in xx.md.