|
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 [email protected] 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 [email protected] 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