You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Apply the following guidelines when authoring blog posts on the VS Code website.
7
+
8
+
## Metadata
9
+
10
+
A blog post must have the following metadata fields, formatted with frontmatter.
11
+
12
+
* Order: sequence number (higher number is more recent)
13
+
* TOCTitle: blog post title used in table of contents - try to keep it shorter than 30 characters
14
+
* PageTitle: blog post title used in the browser tab
15
+
* MetaDescription: short description of the blog post, used for SEO purposes - keep it shorter than 160 chars
16
+
* MetaSocialImage: file name of the image used for sharing on social channels - relative path
17
+
* Date: publication date, formatted as YYYY-MM-DD
18
+
* Author: full name of the author(s)
19
+
20
+
## Folder structure
21
+
22
+
A blog post MUST be stored in the `blogs` folder, within a `year/month/day` subfolder structure. Each of the three levels of the date must be subfolder.
23
+
24
+
## Content structure
25
+
26
+
- The blog post title is an H1 heading.
27
+
- There must be a byline directly underneath the title, formatted as `<Month> <day>, <year> by [<author name>](<link to social media profile>))`. The byline must be followed by an empty line.
28
+
- The blog post must be broken into sections with H2 headings.
29
+
- Images should be included using relative paths and must have alt text.
30
+
- Links to documentation articles should use full URLs.
31
+
- Start with a brief introduction that summarizes the main points of the post.
32
+
- End with a call to action, such as encouraging readers to try out a new feature or share their thoughts in the comments.
33
+
- The blog post should end with a line saying `Happy coding! 💙`
34
+
35
+
## Writing style
36
+
37
+
- In general, the blog post should adhere to the docs [writing guidelines](./docs-writing.instructions.md).
38
+
- Blog posts should be engaging and can include a more conversational tone than standard documentation.
39
+
- Use active voice and first-person plural ("we") to create a sense of community and shared experience.
40
+
- Use contractions (e.g., "it's", "we're") to make the writing feel more natural and approachable.
41
+
- The target audience is developers who use VS Code, ranging from beginners to advanced users.
42
+
- Use simple and clear language, avoiding jargon unless it's widely understood by the target audience.
Copy file name to clipboardExpand all lines: .github/instructions/release-notes-writing.instructions.md
+5-2Lines changed: 5 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -60,18 +60,21 @@ You are a technical writer assistant tasked with generating release notes for al
60
60
61
61
## Writing Guidelines
62
62
63
-
Apply these specific guidelines to all release notes. For other text, follow the general [writing guidelines](../copilot-instructions.md).
63
+
Apply these specific guidelines to all release notes. For other text, follow the general [writing guidelines](../instructions/docs-writing.instructions.md).
64
64
65
65
### Headings
66
66
67
+
- Always use sentence case for headings, so only the first word is capitalized.
67
68
- Don't apply an inline style like italic, bold, or inline code style to headings.
68
-
- Lowercase everything except the first word in a heading.
69
69
70
70
### Links
71
71
72
72
- Links to other documentation articles should be absolute, not relative. Start absolute links with `https://code.visualstudio.com/docs/` and don't include the `.md` suffix.
73
73
- Link text should be descriptive and clearly indicate the content of the linked article. Don't use "click here" or "this link" or "here".
74
+
- Image links MUST have an alt text that describes the image content, not the image file name, and start with "Screenshot showing".
75
+
- Video links MUST have an alt text that describes the video content, not the video file name, and start with "Video showing".
74
76
75
77
### Text Formatting
76
78
77
79
- Notes and tips are formatted as block quotes with the word "Note" or "Tip" in bold at the start of the line. Don't use alert-style formatting for these.
80
+
- Use asterisks for lists, not hyphens or numbers.
You are an expert in answering questions about Visual Studio Code, its features, and how to use it effectively. Explain how specific features work, give examples of usage scenarios.
7
+
8
+
Ground your answers in the source code by using #githubRepo microsoft/vscode and microsoft/vscode-copilot-chat.
9
+
10
+
Provide references to where you found the information in the source code.
Review the article for clarity, conciseness, and adherence to our documentation [writing style guidelines](../instructions/docs-writing.instructions.md).
7
6
8
-
Provide concrete and practical suggestions for improvement.
7
+
Review a documentation article by completing these tasks:
9
8
10
-
Provide your feedback in the form of a Markdown task list, with each task starting with `- [ ]`.
9
+
* Review the article for adherence to our documentation [writing style guidelines](../instructions/docs-writing.instructions.md).
10
+
11
+
* Validate technical accuracy:
12
+
- Verify all code samples are syntactically correct and follow best practices
13
+
- Test command-line instructions and procedures
14
+
- Confirm API references and method names are current
15
+
- Check that screenshots and images are up-to-date
16
+
17
+
* Evaluate structural organization:
18
+
- The title accurately reflects the content
19
+
- The metadata description is concise, informative, and optimized for SEO
20
+
- The introduction provides a clear overview of the article's purpose
21
+
- Sections are logically organized with proper heading hierarchy
22
+
- Content flows logically without redundancy or repetitive language
23
+
- Relevant next steps or related articles are linked at the end
24
+
25
+
After your analysis, provide a summary of your findings and actionable feedback for improvement. Group your findings into these categories: "Technical Accuracy," "Style and Grammar," "Structure and Organization," "Accessibility," and "SEO Optimization." For each category, list specific issues identified and suggest concrete improvements with examples.
description: You are a technical writer reviewing a VS Code release notes for clarity, conciseness, and adherence to the writing style guidelines.
5
+
---
6
+
Review the article for clarity, conciseness, and adherence to our [release notes writing style guidelines](../instructions/release-notes-writing.instructions.md).
7
+
8
+
Provide a concise summary of the key changes and improvements highlighted in the release notes.
9
+
Provide concrete and practical suggestions for improvement.
0 commit comments