|
6 | 6 | - [Write Article Draft](#write-article-draft) |
7 | 7 | - [Write Code](#write-code) |
8 | 8 |
|
9 | | -## Style Guidelines |
| 9 | +## Writing Checklist |
10 | 10 |
|
11 | | -### Tone and Structure |
| 11 | +### Writing Style Checklist |
12 | 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) |
| 13 | +- [ ] Use action verbs instead of passive voice |
| 14 | +- [ ] Limit paragraphs to 2-4 sentences |
| 15 | +- [ ] For every major code block, provide a clear explanation of what it does and why it matters. |
| 16 | +- [ ] Structure content for quick scanning with clear headings and bullet points |
17 | 17 |
|
18 | | -### Data Science Focus |
| 18 | +### Data Science-Focused Writing Checklist |
19 | 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 |
| 20 | +- [ ] Write for data scientists comfortable with Python but unfamiliar with this specific tool or library. |
| 21 | +- [ ] Use examples that align with common data science workflows or problems |
| 22 | +- [ ] Highlight **only** the features that matter to a data science audience |
24 | 23 |
|
25 | | -### Reader Experience Assumptions |
| 24 | +### Structure Checklist |
26 | 25 |
|
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 |
| 26 | +- [ ] Start with a real, practical data science problem |
| 27 | +- [ ] Explain how each tool solves the problem |
| 28 | +- [ ] Use diagrams or charts to explain complex ideas, when appropriate. |
| 29 | +- [ ] Define new concepts and terminology |
| 30 | +- [ ] Only include the essential setup steps needed to run the examples. For anything beyond that, link to the official documentation. |
30 | 31 |
|
31 | 32 | ## Write Article Draft |
32 | 33 |
|
|
0 commit comments