|
2 | 2 |
|
3 | 3 | ## Table of Contents
|
4 | 4 |
|
5 |
| -### Writing Code |
6 |
| -- [Environment Setup](#environment-setup) |
7 |
| - - [Install uv](#install-uv) |
8 |
| - - [Install Dependencies](#install-dependencies) |
9 |
| - - [Install Pre-commit Hooks](#install-pre-commit-hooks) |
10 |
| -- [Working with Marimo Notebooks](#working-with-marimo-notebooks) |
11 |
| - - [Creating a New Notebook](#creating-a-new-notebook) |
12 |
| - - [Publishing Notebooks](#publishing-notebooks) |
13 |
| -- [Pull Request Process](#pull-request-process) |
14 |
| - |
15 |
| -### Writing Blog |
16 |
| -- [Using HackMD](#using-hackmd) |
17 |
| -- [Writing Style Guidelines](#writing-style-guidelines) |
18 |
| - |
19 |
| -## Writing Code |
| 5 | +- [Style Guidelines](#style-guidelines) |
| 6 | +- [Write Article Draft](#write-article-draft) |
| 7 | +- [Write Code](#write-code) |
| 8 | + |
| 9 | +## Style Guidelines |
| 10 | + |
| 11 | +### Tone and Structure |
| 12 | + |
| 13 | +- Use direct, conversational language |
| 14 | +- Keep paragraphs short (2-4 sentences maximum) |
| 15 | +- Prioritize comprehensive but concise explanations without repetition |
| 16 | +- Maintain a balanced ratio of explanation to code (approximately 50/50) |
| 17 | + |
| 18 | +### Data Science Focus |
| 19 | + |
| 20 | +- Begin with a real, practical data science problem before introducing the tool |
| 21 | +- Focus on how each tool or feature helps solve that problem |
| 22 | +- Always explain the **practical value** of a feature (e.g., saves time, reduces costs, enables offline workflows) |
| 23 | +- Avoid tool-first framing. Tools should support a use case, not be the center of the article |
| 24 | + |
| 25 | +### Reader Experience Assumptions |
| 26 | + |
| 27 | +- Assume readers are data scientists who have basic programming knowledge but may be new to specific tools |
| 28 | +- Write for readers who scan, not follow step-by-step; they want to *understand*, not necessarily *run* the code |
| 29 | +- When mentioning install commands or configuration flags, keep them minimal and link out to official docs for details |
| 30 | + |
| 31 | +## Write Article Draft |
| 32 | + |
| 33 | +1. Create your blog post in [HackMD](https://hackmd.io) |
| 34 | +2. Follow [these instructions](https://hackmd.io/c/tutorials/%2F%40docs%2Finvite-others-to-a-private-note-en) to share your draft with khuyentran@codecut.ai for review |
| 35 | + |
| 36 | +## Write Code |
20 | 37 |
|
21 | 38 | ### Environment Setup
|
22 | 39 |
|
@@ -94,31 +111,3 @@ The exported HTML files will be automatically deployed to GitHub Pages through t
|
94 | 111 | 3. Make your changes
|
95 | 112 | 4. Submit a pull request with a clear description of changes
|
96 | 113 |
|
97 |
| -## Writing Blog |
98 |
| - |
99 |
| -### Using HackMD |
100 |
| - |
101 |
| -1. Create your blog post in [HackMD](https://hackmd.io) |
102 |
| -2. Follow [these instructions](https://hackmd.io/c/tutorials/%2F%40docs%2Finvite-others-to-a-private-note-en) to share your draft with khuyentran@codecut.ai for review |
103 |
| - |
104 |
| -### Writing Style Guidelines |
105 |
| - |
106 |
| -#### Tone and Structure |
107 |
| - |
108 |
| -- Use direct, conversational language |
109 |
| -- Keep paragraphs short (2-4 sentences maximum) |
110 |
| -- Prioritize comprehensive but concise explanations without repetition |
111 |
| -- Maintain a balanced ratio of explanation to code (approximately 50/50) |
112 |
| - |
113 |
| -#### Data Science Focus |
114 |
| - |
115 |
| -- Begin with a real, practical data science problem before introducing the tool |
116 |
| -- Focus on how each tool or feature helps solve that problem |
117 |
| -- Always explain the **practical value** of a feature (e.g., saves time, reduces costs, enables offline workflows) |
118 |
| -- Avoid tool-first framing. Tools should support a use case, not be the center of the article |
119 |
| - |
120 |
| -#### Reader Experience Assumptions |
121 |
| - |
122 |
| -- Assume readers are data scientists who have basic programming knowledge but may be new to specific tools |
123 |
| -- Write for readers who scan, not follow step-by-step; they want to *understand*, not necessarily *run* the code |
124 |
| -- When mentioning install commands or configuration flags, keep them minimal and link out to official docs for details |
0 commit comments