Writing & Publication Skill
Patterns for technical writing, academic publication, and content strategy.
Writing Formats
| Format |
Audience |
Length |
Review |
| Academic Paper |
Researchers |
4-10K words |
Peer (2-6 mo) |
| Workshop Paper |
Researchers |
2-4K words |
Light (1-2 mo) |
| Trade Publication |
Practitioners |
1-2K words |
Editorial (2-4 wk) |
| Blog Post |
Developers |
500-1.5K words |
Self |
| Documentation |
Users |
Variable |
Internal |
Academic Paper Structure
- Abstract — Problem, approach, results, implications (150-300 words)
- Introduction — Motivation, problem, contributions, outline
- Related Work — Position within existing research
- Methodology — How you did it (reproducible)
- Implementation — Technical details (if applicable)
- Evaluation — Evidence for claims
- Discussion — Interpretation, limitations
- Conclusion — Summary, future work
- References — Venue-specific format
Writing Principles
- Precision over flair
- Evidence for claims (data or citations)
- Acknowledge limitations
- Active voice preferred
- Define terms on first use
- Break sentences at 25-30 words
Pitfalls to Avoid
| Bad |
Fix |
| "might possibly perhaps" |
"may" |
| "revolutionary" |
"novel approach" |
| "was performed" |
"we performed" |
| Jargon without definition |
Define on first use |
| Buried contributions |
State explicitly in intro |
Structuring Arguments
CARS Model (Introductions):
- Establish territory (topic importance)
- Establish niche (gap in knowledge)
- Occupy niche (your contribution)
Heilmeier Catechism (Motivation):
- What are you trying to do?
- How is it done today? Limits?
- What's new in your approach?
- Who cares? What difference?
- What are the risks?
Audience Adaptation
| Audience |
Adjust |
| Researchers |
Add theoretical framing, citations |
| Practitioners |
Add code examples |
| Executives |
Add business value |
| General tech |
Remove jargon |
Publication Strategy
Venue sequencing:
- Trade publication → immediate visibility
- arXiv pre-print → establish priority
- Workshop paper → academic credibility
- Journal/conference → peer-reviewed validation
First-time author:
- Start with lower-barrier venues
- Collaborate with established authors
- Target workshops first
- Conduct user studies (empirical data strengthens)
Responding to Reviews
| Feedback |
Response |
| "Missing related work" |
Add citations, explain positioning |
| "Claims not supported" |
Add evidence or soften claims |
| "Unclear methodology" |
Expand description |
| "Limited evaluation" |
Add studies or acknowledge |
Response letter: Thank → Summarize changes → Address each point → Highlight extras
Pre-Submission Checklist
Word-Compatible Research Writing Style
Conventions for research documents authored in Markdown and converted to Word via Pandoc or md-to-word.
Punctuation Rules
| Instead of |
Use |
When |
| Em-dash (—) |
Colon (:) |
Elaboration or definition: "The framework provides: integration across domains" |
| Em-dash (—) |
Comma (,) |
Parenthetical aside: "The model, originally designed for therapy, applies broadly" |
| Em-dash (—) |
Semicolon (;) |
Related independent clauses: "The theory is sound; the implementation follows" |
| Em-dash (—) |
Period (.) |
Full sentence break: "This completes Phase 1. The next phase begins" |
| Double-hyphen (--) |
Same as above |
Never use -- as a substitute; apply proper punctuation directly |
Definition List Formatting
Use bold term followed by colon, no dash separators:
<!-- Bad -->
**Term** — description
**Term** -- description
<!-- Good -->
**Term**: description
Formal Tone
| Avoid |
Use |
| Contractions (isn't, it's, don't) |
Full forms (is not, it is, do not) |
| Em-dashes for drama |
Colons for precision |
| First person plural ("we find") |
Active voice with subject ("the analysis reveals") |
Markdown Elements to Avoid for Word
| Element |
Problem |
Alternative |
--- horizontal rules |
Renders as full-width line in Word |
Use headings or blank lines for separation |
\n in Mermaid labels |
Not rendered; breaks labels |
Use <br/> for line breaks |
| Nested blockquotes |
Inconsistent Word rendering |
Use single-level blockquotes only |
| HTML tags in body text |
May not convert |
Use pure Markdown |
APA 7 Conventions for Markdown
- In-text citations: parenthetical
(Author, Year) or narrative Author (Year)
- References: alphabetical by last name, hanging indent, sentence-case titles
- Title page: title, authors, date, abstract paragraph (no page numbers in Markdown)
- Headings: H1 for title, H2 for major sections, H3 for subsections (maps to APA levels)
- Tables: include descriptive captions above, notes below
- Figures: Mermaid diagrams count as figures; caption with "Figure N." prefix
Mermaid Diagram Conventions for Research
- Use
%%{init: {'theme': 'base', 'themeVariables': {...}}}%% for consistent styling
- Line breaks:
<br/> only; never \n
- Keep node text concise; move detail to surrounding prose
- GitHub Pastel v2 palette for professional appearance
- Export as PNG before Word conversion if diagram fidelity is critical
Tools
| Tool |
Purpose |
| Overleaf |
LaTeX collaboration |
| Grammarly |
Grammar/style |
| Zotero |
References |
| Connected Papers |
Literature discovery |
| Pandoc |
Markdown to Word conversion |
| md-to-word skill |
Markdown + Mermaid to Word pipeline |
Synapses
See synapses.json for connections.
1---2name: writing-publication-skill3description: Patterns for technical writing, academic publication, content strategy, and Word-compatible research formatting.4---5
6# Writing & Publication Skill
7
8> Patterns for technical writing, academic publication, and content strategy.
9
10## Writing Formats
11
12| Format | Audience | Length | Review |
13| ------ | -------- | ------ | ------ |
14| Academic Paper | Researchers | 4-10K words | Peer (2-6 mo) |
15| Workshop Paper | Researchers | 2-4K words | Light (1-2 mo) |
16| Trade Publication | Practitioners | 1-2K words | Editorial (2-4 wk) |
17| Blog Post | Developers | 500-1.5K words | Self |
18| Documentation | Users | Variable | Internal |
19
20## Academic Paper Structure
21
221. **Abstract** — Problem, approach, results, implications (150-300 words)
232. **Introduction** — Motivation, problem, contributions, outline
243. **Related Work** — Position within existing research
254. **Methodology** — How you did it (reproducible)
265. **Implementation** — Technical details (if applicable)
276. **Evaluation** — Evidence for claims
287. **Discussion** — Interpretation, limitations
298. **Conclusion** — Summary, future work
309. **References** — Venue-specific format
31
32## Writing Principles
33
34- Precision over flair
35- Evidence for claims (data or citations)
36- Acknowledge limitations
37- Active voice preferred
38- Define terms on first use
39- Break sentences at 25-30 words
40
41## Pitfalls to Avoid
42
43| Bad | Fix |
44| --- | --- |
45| "might possibly perhaps" | "may" |
46| "revolutionary" | "novel approach" |
47| "was performed" | "we performed" |
48| Jargon without definition | Define on first use |
49| Buried contributions | State explicitly in intro |
50
51## Structuring Arguments
52
53**CARS Model (Introductions):**
54
551. Establish territory (topic importance)
562. Establish niche (gap in knowledge)
573. Occupy niche (your contribution)
58
59**Heilmeier Catechism (Motivation):**
60
61- What are you trying to do?
62- How is it done today? Limits?
63- What's new in your approach?
64- Who cares? What difference?
65- What are the risks?
66
67## Audience Adaptation
68
69| Audience | Adjust |
70| -------- | ------ |
71| Researchers | Add theoretical framing, citations |
72| Practitioners | Add code examples |
73| Executives | Add business value |
74| General tech | Remove jargon |
75
76## Publication Strategy
77
78**Venue sequencing:**
79
801. Trade publication → immediate visibility
812. arXiv pre-print → establish priority
823. Workshop paper → academic credibility
834. Journal/conference → peer-reviewed validation
84
85**First-time author:**
86
87- Start with lower-barrier venues
88- Collaborate with established authors
89- Target workshops first
90- Conduct user studies (empirical data strengthens)
91
92## Responding to Reviews
93
94| Feedback | Response |
95| -------- | -------- |
96| "Missing related work" | Add citations, explain positioning |
97| "Claims not supported" | Add evidence or soften claims |
98| "Unclear methodology" | Expand description |
99| "Limited evaluation" | Add studies or acknowledge |
100
101**Response letter**: Thank → Summarize changes → Address each point → Highlight extras
102
103## Pre-Submission Checklist
104
105- [ ] Abstract stands alone
106- [ ] Contributions stated in intro
107- [ ] Claims supported by evidence
108- [ ] Limitations acknowledged
109- [ ] References complete
110- [ ] Figures/tables readable
111- [ ] Page limit respected
112- [ ] Code available (if applicable)
113
114## Word-Compatible Research Writing Style
115
116Conventions for research documents authored in Markdown and converted to Word via Pandoc or md-to-word.
117
118### Punctuation Rules
119
120| Instead of | Use | When |
121| ---------- | --- | ---- |
122| Em-dash (—) | Colon (:) | Elaboration or definition: "The framework provides: integration across domains" |
123| Em-dash (—) | Comma (,) | Parenthetical aside: "The model, originally designed for therapy, applies broadly" |
124| Em-dash (—) | Semicolon (;) | Related independent clauses: "The theory is sound; the implementation follows" |
125| Em-dash (—) | Period (.) | Full sentence break: "This completes Phase 1. The next phase begins" |
126| Double-hyphen (--) | Same as above | Never use -- as a substitute; apply proper punctuation directly |
127
128### Definition List Formatting
129
130Use bold term followed by colon, no dash separators:
131
132```markdown
133<!-- Bad -->
134**Term** — description
135**Term** -- description
136
137<!-- Good -->
138**Term**: description
139```
140
141### Formal Tone
142
143| Avoid | Use |
144| ----- | --- |
145| Contractions (isn't, it's, don't) | Full forms (is not, it is, do not) |
146| Em-dashes for drama | Colons for precision |
147| First person plural ("we find") | Active voice with subject ("the analysis reveals") |
148
149### Markdown Elements to Avoid for Word
150
151| Element | Problem | Alternative |
152| ------- | ------- | ----------- |
153| `---` horizontal rules | Renders as full-width line in Word | Use headings or blank lines for separation |
154| `\n` in Mermaid labels | Not rendered; breaks labels | Use `<br/>` for line breaks |
155| Nested blockquotes | Inconsistent Word rendering | Use single-level blockquotes only |
156| HTML tags in body text | May not convert | Use pure Markdown |
157
158### APA 7 Conventions for Markdown
159
160- **In-text citations**: parenthetical `(Author, Year)` or narrative `Author (Year)`
161- **References**: alphabetical by last name, hanging indent, sentence-case titles
162- **Title page**: title, authors, date, abstract paragraph (no page numbers in Markdown)
163- **Headings**: H1 for title, H2 for major sections, H3 for subsections (maps to APA levels)
164- **Tables**: include descriptive captions above, notes below
165- **Figures**: Mermaid diagrams count as figures; caption with "Figure N." prefix
166
167### Mermaid Diagram Conventions for Research
168
169- Use `%%{init: {'theme': 'base', 'themeVariables': {...}}}%%` for consistent styling
170- Line breaks: `<br/>` only; never `\n`
171- Keep node text concise; move detail to surrounding prose
172- GitHub Pastel v2 palette for professional appearance
173- Export as PNG before Word conversion if diagram fidelity is critical
174
175## Tools
176
177| Tool | Purpose |
178| ---- | ------- |
179| Overleaf | LaTeX collaboration |
180| Grammarly | Grammar/style |
181| Zotero | References |
182| Connected Papers | Literature discovery |
183| Pandoc | Markdown to Word conversion |
184| md-to-word skill | Markdown + Mermaid to Word pipeline |
185
186## Synapses
187
188See [synapses.json](synapses.json) for connections.
majiayu000