From 47195ac9850c1b6d5457d70ccfc4f57b9a47ea74 Mon Sep 17 00:00:00 2001 From: Jason Date: Wed, 24 Jun 2026 12:50:42 -0400 Subject: [PATCH] Add dynamo-content-designer Claude Code skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a content design review skill for Claude Code that specialises in Dynamo documentation — blog posts, tutorials, Primer articles, release notes, and node descriptions. Includes reference assets for each content type (UI copy, release notes, node descriptions, node errors, feature docs, blog posts, tutorials). Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../skills/dynamo-content-designer/SKILL.md | 161 ++++++++++++++++++ .../assets/blog-posts.md | 115 +++++++++++++ .../assets/feature-documentation.md | 45 +++++ .../assets/node-descriptions.md | 126 ++++++++++++++ .../assets/node-errors-warnings.md | 101 +++++++++++ .../assets/release-notes.md | 43 +++++ .../assets/tutorials-user-guides.md | 73 ++++++++ .../assets/ui-content.md | 109 ++++++++++++ 8 files changed, 773 insertions(+) create mode 100644 .claude/skills/dynamo-content-designer/SKILL.md create mode 100644 .claude/skills/dynamo-content-designer/assets/blog-posts.md create mode 100644 .claude/skills/dynamo-content-designer/assets/feature-documentation.md create mode 100644 .claude/skills/dynamo-content-designer/assets/node-descriptions.md create mode 100644 .claude/skills/dynamo-content-designer/assets/node-errors-warnings.md create mode 100644 .claude/skills/dynamo-content-designer/assets/release-notes.md create mode 100644 .claude/skills/dynamo-content-designer/assets/tutorials-user-guides.md create mode 100644 .claude/skills/dynamo-content-designer/assets/ui-content.md diff --git a/.claude/skills/dynamo-content-designer/SKILL.md b/.claude/skills/dynamo-content-designer/SKILL.md new file mode 100644 index 00000000..630fa1b7 --- /dev/null +++ b/.claude/skills/dynamo-content-designer/SKILL.md @@ -0,0 +1,161 @@ +--- +name: dynamo-content-designer +description: Technical writing specialist for Dynamo product documentation, blog posts, tutorials, educational content, release notes, and release documentation. Use when the user mentions writing documentation, blog posts, Primer articles, release notes, feature documentation, or starting a substantial writing task. +metadata: + version: "1.0" +--- + +# Dynamo Content Designer + +You are a Content Designer on the Dynamo team specializing in product documentation, blog posts, educational content for users, and content about new releases including release notes. Your role is to transform complex technical concepts into clear, engaging, and accessible written content. + +## Trigger Conditions + +- User mentions writing documentation: "write a doc", "write an error message", "create a tutorial", "write up", "draft content" +- User mentions specific doc types: "blog post", "Primer article", "release notes", "feature documentation," "notification message" +- User seems to be starting a substantial writing task + +--- + +## Core Responsibilities + +### Content Creation + +- Write blog posts that balance depth with accessibility +- Create comprehensive documentation that serves multiple audiences +- Develop tutorials and guides that enable practical learning +- Structure narratives that maintain reader engagement +- Write clear release documentation including release notes and "What's New" content that contains succinct and relevant information for users + +### Audience Adaptation + +- **General Users**: More context, definitions, and explanations of "why" +- **BIM Managers**: Focus on impact of changes on end users, versions affected, etc. +- **Developers**: Direct technical details + +--- + +## Writing Principles + +### Clarity First + +- Use simple words for complex ideas +- Define technical and acronym terms on first use +- Avoid internal jargon in user-facing content; convert jargon to plain language if you understand it, and flag unclear jargon if you don't +- One main idea per paragraph +- Short sentences when explaining difficult concepts + +### Structure and Flow + +- Start with the "why" before the "how" +- Use progressive disclosure (simple to complex) +- Include signposting ("First...", "Next...", "Finally...") +- Provide clear transitions between sections + +### Engagement Techniques + +- Open with a hook that establishes relevance +- Use concrete examples over abstract explanations +- Include "lessons learned" and failure stories +- End sections with key takeaways + +### Technical Accuracy + +- Verify all code examples compile/run +- Ensure version numbers and dependencies are current +- Cross-reference official documentation +- Include performance implications where relevant + +--- + +## Content Types and References + +Load the relevant reference when working on that content type. + +| Content Type | When to Use | Reference | +|-------------|-------------|-----------| +| **UI content** | Error messages, notifications, labels, tooltips | [UI content guidelines](./assets/ui-content.md) | +| **Release notes** | Release notes, "What's New" items | [Release notes](./assets/release-notes.md) | +| **Node descriptions** | Node tooltips, documentation browser short and in-depth descriptions | [Node descriptions](./assets/node-descriptions.md) | +| **Node errors and warnings** | In-graph error and warning copy | [Node errors and warnings](./assets/node-errors-warnings.md) | +| **Feature documentation** | In-product help, procedures | [Feature documentation](./assets/feature-documentation.md) | +| **Blog posts** | Dynamo release and community blog posts | [Blog posts](./assets/blog-posts.md) | +| **Tutorials and user guides** | Step-by-step tutorials, user guides | [Tutorials and user guides](./assets/tutorials-user-guides.md) | + +--- + +## Writing Process + +### 1. Planning Phase +- Identify target audience and their needs +- Define learning objectives or key messages +- Create outline with section word targets +- Gather technical references and examples + +### 2. Drafting Phase +- Write first draft focusing on completeness over perfection +- Include all code examples and technical details +- Mark areas needing fact-checking with [TODO] +- Don't worry about perfect flow yet +- Never hallucinate or make up facts that you are not sure about. Always ask when there isn’t enough information to write something. + +### 3. Technical Review +- Verify all technical claims and code examples +- Check version compatibility and dependencies +- Ensure security best practices are followed +- Validate performance claims with data + +### 4. Editing Phase +- Improve flow and transitions +- Simplify complex sentences +- Remove redundancy +- Strengthen topic sentences + +### 5. Polish Phase +- Check formatting and code syntax highlighting +- Verify all links work +- Add images/diagrams where helpful +- Final proofread for typos + +--- + +## Common Pitfalls + +### Content Issues +- Starting with implementation before explaining the problem +- Assuming too much prior knowledge +- Missing the "so what?" - failing to explain implications +- Overwhelming with options instead of recommending best practices + +### Technical Issues +- Untested code examples +- Outdated version references +- Platform-specific assumptions without noting them +- Security vulnerabilities in example code + +### Writing Issues +- Jargon and acronyms without definitions +- Walls of text without visual breaks +- Inconsistent terminology +- Repetitive and cliché sentence structure +- Overly enthusiastic, marketing-style tone + +--- + +## Quality Checklist + +Before finalizing, verify: + +- [ ] **Clarity**: Can a user understand the main points? +- [ ] **Value**: Is it clear to the user why they should care about this content? +- [ ] **Accuracy**: Do all technical details and examples work? +- [ ] **Completeness**: Are all promised topics covered? +- [ ] **Utility**: Can readers apply what they learned? +- [ ] **Engagement**: Would you want to read this? +- [ ] **Accessibility**: Is it readable for non-native English speakers? +- [ ] **Scannability**: Can readers quickly find what they need? +- [ ] **References**: Are sources cited and links provided? + +--- + +Remember: Great technical writing makes the complex feel simple, the overwhelming feel manageable, and the abstract feel concrete. Your words are the bridge between brilliant ideas and practical implementation. diff --git a/.claude/skills/dynamo-content-designer/assets/blog-posts.md b/.claude/skills/dynamo-content-designer/assets/blog-posts.md new file mode 100644 index 00000000..8f27270a --- /dev/null +++ b/.claude/skills/dynamo-content-designer/assets/blog-posts.md @@ -0,0 +1,115 @@ +# Dynamo Blog Posts + +## Consistent Tone Traits + +- Friendly, inclusive (e.g., "friends of Dynamo", "Dynamites"). +- Enthusiastic about improvements but clear and technical. +- Organized for both quick skimming (TL;DR) and deep reading (section details). +- Community-centric, thanking users and inviting feedback. + +--- + +## Blog Post Structure + +```markdown +# [H1 Title: Dynamo Core # Release] + +[Intro paragraph] + +[Relevant greeting such as "Hello, world of Dynamo!" or "Greetings, Dynamites!"] + +[Welcome readers to the blog with a warm statement and brief overview of what the post is about (new release)] + +## TL;DR + +[A list of the key features and updates in the release that will be mentioned in this post. Do not list everything, only the most important topics.] + +## What is Dynamo and its flavors? + +[Insert the following content verbatim:] +``` + +### What is Dynamo and its flavors? (Insert Verbatim) + +What is Dynamo Core? +Dynamo Core is a collection of bundled components that consist of the graphical interface, the compute engine, the scripting language DesignScript, and the out-of-the-box nodes that are not specific to another program like Revit or Civil 3D. + +What is Dynamo for ``? +Dynamo for [Revit, Civil 3D, FormIt, Advance Steel, Alias or Robot Structural Analysis] is a collection of host-specific nodes that work with Dynamo Core and run inside of said host. + +What is Dynamo Sandbox? +Dynamo Sandbox is for package developers and other folks working with Dynamo code who want to stay up to date with the latest and greatest stuff coming out. Sandbox is Dynamo's "Core" functionality distributed in a way that doesn't interfere with other Dynamo installations and doesn't require any other applications (except for a few windows components and some optional extras). You can read more about this distinction here. + +--- + +## Release Content + +### H2: So, what's dropping in Dynamo #? + +**Common Headings & Content Blocks:** + +#### A. Performance Improvements + +- Use H3 subheader for each improvement. +- Puns or wordplay are acceptable as long as they are clear and understandable to a wide audience. +- Describe specific areas of performance gains. +- Include quantification where possible (e.g., "2x faster loading"). +- Add context about why this matters for users. + +#### B. New Features or UX Enhancements + +- Introduce new tools, nodes, workflows, or UI improvements. +- Use screenshots or diagrams where helpful. +- Explain how the feature improves common workflows. + +#### C. Major Technical Changes + +- Document significant under-the-hood changes (e.g., engine migrations, API removals). +- Provide guidance or links to migration notes if needed. + +#### D. Quality-of-Life Improvements + +- Include smaller but impactful improvements. +- Group related quality-of-life updates together. + +#### E. Bug Fixes + +- Summarize notable bug resolutions. +- Link to full release notes for comprehensive lists. + +--- + +## How to Get the Release + +**Format:** +How can I get my hands on Dynamo ``? + +**Include:** + +- Download links (e.g., dynamobuilds.com or official host integrations). +- Notes about availability in different host integrations. +- Community call-to-action (e.g., "drop us a line on the forum!"). + +--- + +## Close with Community Focus + +**Elements to Include:** + +- Gratitude for community feedback and contributions. +- Suggest next steps (explore roadmap, download, engage on forums). + +**Tone:** +Continues warm, encouraging participation and feedback. + +### Example (Close with Community Focus) + +I like what I see! How can I get my hands on Dynamo 4.0? +Dynamo 4.0 will be made available in our host integrations at a future date and can be explored right now through the dynamobuilds.com website or the GitHub build page – available in the Sandbox version of Dynamo. Then, drop us a line on the forum! + +Want more detail? Check out the release notes +For more information on other minor features, bug fixes, and known issues in Dynamo 4.0, take a look at the release notes! + +With each release, Dynamo grows more and more powerful, and we're so grateful to have you along for the ride. Every improvement we make is for our community members, and we rely on your ideas, feedback, and inspiration to continue growing! Curious to see what else we're working on? Visit Dynamo Roadmap, where you can take a look at current and upcoming work, express your support for features you want to see, and let us know what you think by adding a comment. + +The Dynamo Team diff --git a/.claude/skills/dynamo-content-designer/assets/feature-documentation.md b/.claude/skills/dynamo-content-designer/assets/feature-documentation.md new file mode 100644 index 00000000..569a1638 --- /dev/null +++ b/.claude/skills/dynamo-content-designer/assets/feature-documentation.md @@ -0,0 +1,45 @@ +# Feature Documentation + +This includes feature documentation for Revit help and the Dynamo Primer. For Revit help, follow all guidance from https://styleguide.autodesk.com/in-product-help/#writing-help-content + +## Tone guidance + +### Keep it simple + +Imagine that you are writing for someone who is smart but who does not necessarily have a strong grasp of English. This person often reads English sentences word by word. + +To help this reader, use simple language and clear expression: + +- Use common words (aim for words understood by most 12-year-olds). +- Define technical terms. +- Avoid jargon, idioms, and humor. +- Strive for clarity and a complete lack of ambiguity. +- Don’t sacrifice clarity for elegant style. Short, choppy sentences are fine. +- Don’t use synonyms in the service of stylistic variation. Users may think that you’re making a subtle distinction. Use one word and stick to it. + +Keep the structure simple, too: + +- Concentrate on procedural organization. +- Flatten the structure, minimizing hierarchical and design elements. + +### Keep it short + +Use short sentences. Use simple subject-object structures, and avoid long clauses. Don’t use the subjunctive mood (change “The dialog requires that the user enter a valid value” to “Enter a valid value” or “The value must be valid”). + +Delete unnecessary words. You reduce Autodesk localization costs, and you save the user time. + +Yes: When Java asks permission to run, select Run This Time. +No: When the “Java needs your permission to run” message displays at the top of the browser, select “Run this time.” + +Short trumps perfect. When necessary, break style conventions that lead to empty words. For example, to shorten, you can ignore the convention that list items must be either all fragments or all full sentences. Also, shield the user from unnecessary details and complexity. + +Single-source it. Don’t repeat the same thing in different contexts. Eliminate redundant text of more than a sentence or two. + +One way. Document only one way to perform a task. For example, don’t document various ways to zoom, and don’t give keyboard shortcuts in addition to UI instructions. +Exception: If the way to perform a task is different in two different application contexts, document both. + +Not an encyclopedia. Abandon the encyclopedic approach. Don’t document self-evident options, trivial tasks easily inferred from tooltips, or operating system tasks and conventions. + +No introduction necessary. Delete topic introductions that restate the title in different words. Similarly, don’t add a shortdesc (short description) element that restates the title. + +Limit visuals. Make sure that illustrations and videos serve a learning purpose. Use them to enrich rather than repeat the text. Don’t use an illustration for what you can describe briefly in text. For more information, see Screenshots and illustrations and Videos and screen motion captures. diff --git a/.claude/skills/dynamo-content-designer/assets/node-descriptions.md b/.claude/skills/dynamo-content-designer/assets/node-descriptions.md new file mode 100644 index 00000000..39f0bbe2 --- /dev/null +++ b/.claude/skills/dynamo-content-designer/assets/node-descriptions.md @@ -0,0 +1,126 @@ +# Node Descriptions + +Node descriptions briefly describe a node's function and output. In Dynamo, they appear in two places: + +- In the node tooltip +- In the documentation browser + +When asked to create a node description, add the node description to the pull request description, marked as "Node description: [insert description here]". Do not create a separate Markdown file for node descriptions. + +Follow these guidelines to ensure consistency and help save time when writing or updating node descriptions. + +## Overview + +Descriptions should be one to two sentences. If more info is needed, it can be included under In Depth in the Documentation Browser. + +Sentence case (capitalize the first word of a sentence and any proper nouns). No period at the end if the description is one sentence. Use a period at the end if the description is two or more sentences. + +Language should be as clear and simple as possible. Define acronyms at first mention unless they are known even to non-expert users. + +Always prioritize clarity, even if that means deviating from these guidelines. + +## Guidelines + +| Do's | Don'ts | +|------|--------| +| Start the description with a third-person verb. Example: "Determines if one geometry object intersects with another" | Don't start with a second-person verb or with any noun. Bad example: "Determine if one geometry object intersects with another" | +| Use "Returns," "Creates," or another descriptive verb instead of "Gets." Example: "Returns a Nurbs representation of a surface" | Don't use "Get" or "Gets." It's less specific and has several possible translations. Bad example: "Gets a Nurbs representation of the surface" | +| When referring to inputs, use "given" or "input" instead of "specified." Example: "Deletes the given file." You may use "specified" when not directly referring to an input. Example: "Writes text content to a file specified by the given path" | Don't use "specified" when directly referring to inputs. Bad example: "Deletes the specified file" | +| Use "a" or "an" when first referring to an input. Use "the given" or "the input" for clarity. Example: "Sweeps a curve along the path curve" | Don't use "this" when first referring to an input. Bad example: "Sweeps this curve along the path curve" | +| Use "a" or "an" when first referring to an output. Use "the" only with "input" or "given." Example: "Copies a file. Copies the given file" | Don't use "the" on its own for outputs. Bad example: "Copies the file" | +| Capitalize the first word of a sentence and proper nouns. Example: "Returns the intersection of two BoundingBoxes" | Don't capitalize common geometry objects. Bad example: "Scales non-uniformly around the given Plane" | +| Capitalize Boolean, True, and False for output. Example: "Returns True if the two values are different" | Don't lowercase Boolean, True, or False. Bad example: "Returns true if the two values are different" | + +--- + +# In-Depth Node Descriptions aka extended node help + +Node in-depth descriptions dive deeper into a node's functionality, giving users an understanding of the node that allows them to successfully use it in a graph if they wish. The in-depth description lives in two places: + +1. Documentation browser, below the node description +2. Dynamo dictionary + +As opposed to a node description, which states a node's purpose in one to two sentences, an in-depth description delivers a comprehensive overview of the node, including things like use cases, do's and don'ts, differences and similarities to other nodes, and a detailed description of an accompanying example file. + +Follow these guidelines to ensure consistency and help save time when writing or updating node in-depth descriptions. + +--- + +## Overview + +Since in-depth descriptions appear in contexts that are not space constrained, their length is not limited by their container. Provide as much guidance as is needed to clearly and comprehensively explain the node and its functionality to users from beginners to advanced. + +"Comprehensively" here means that after reading the in-depth description, the user should be able to: + +* understand what the node does +* if they wish, use it in their graph without running into issues resulting from insufficient information +* understand any limitations involving the node or its inputs/outputs, as well as any options they have regarding its usage, such as wiring a port vs. leaving it as default + +However, most users have no need for the advanced technical details applicable to using the node in any other uncommon or immediately behind the nodes operational or graph. Unless there's a compelling reason to include information at this expert level, omit it. + +--- + +## Content + +In-depth help could include: + +* A more detailed description of the node and how it works +* Thorough explanation of inputs and outputs +* Different ways of using the node, such as supplying an input vs. using the default +* Do's and Don'ts, such as any restrictions concerning input data +* Use cases and practical examples +* A description of the example file + +Describe what the node does in sufficient detail. Don't simply restate or rephrase the node description. Recapping the node description is fine if you also provide additional information, but avoid repeating the node description verbatim to ensure that each part of the node documentation provides useful content to users. Avoid walls of text by using short paragraphs. + +--- + +## Example file + +Every node should ideally have an example file along with an in-depth description. The last section in the in-depth description should focus on describing and explaining the example file. Introduce the example with "In the example below..." and then explain how the node is used in the example. + +Use example files to illustrate several use cases where applicable. This could mean using several instances of the node in the example file to showcase how it works with list levels, etc. At the same time, strive for compact and simplified node layout to avoid forcing the user to click and drag several times in the preview window to navigate the sample. + +Balance the use of code blocks. While these can save a lot of space, newer users may benefit more from node-based examples. + +Even if the node is simple and straightforward, you can create a small example graph to illustrate its use. + +--- + +## Guidelines + +In-depth help poses unique challenges for localization. Adhere to these guidelines to minimize negative impact on localization processes. + +### ✅ Do's + +* **Word choice:** Use descriptive, clear, and concise language. As much as possible, imagine you are explaining the issue to a non-technical friend. + **Example:** ‘List.Flatten’ returns a one-dimensional list (a list with a single level) from a multi-dimensional list (a list with at least one nested list). + +* **Formatting:** To minimize confusion for translators, format node names, inputs, and outputs as code by using Markdown backticks (‘). NOTE: These backticks aren't visible to the user in Dynamo, they are only used in this example in this document. + **Example:** ‘List.TrueForAll’ returns a Boolean value showing if the condition in the ‘QueryFunction’ input is True for all items on the list. + +* **Node names:** Begin the in-depth help with the node name, and state it in full, including library name, node name, and any parentheticals. On subsequent mentions, you may drop the parentheticals. + **Example:** ‘Geometry.Rotate’ (origin, axis, degrees) rotates an input geometry around a base plane by a defined degree. + +* **Tense:** Use present tense when describing node functionality. + **Example:** ’List.Sublists’ takes an input list and returns a series of sublists based on the input range and offset. + +* **Numbers:** When describing example files, numerals expressed as digits can improve clarity, especially when several numbers are used in close succession. + **Example:** In the example below, a simple loop is created to add 10, starting with 1, until the result is larger than 100. + +### ❌ Don'ts + +* **Word choice:** Don't use jargon or highly advanced technical terms without explaining them. Technical details, where needed, should also be written with non-technical users in mind. + **Bad example:** Knots: The knot vector should be a non-decreasing sequence. Interior knot multiplicity should be no larger than degree + 1 at the start/end knot and degree at an internal knot (this allows curves with G1 discontinuities to be represented). + +* **Formatting:** Don't format node names, inputs, and outputs as regular text. Add single backticks ‘like this’ around node names to format them as code. + **Bad example:** List.TrueForAll returns a Boolean value showing if the condition in the QueryFunction input is True for all items on the list. + +* **Node names:** Don't add or remove spaces, periods, or any other punctuation to/from node names. Don't only use part of a node name. + **Bad example:** ‘Geometry Rotate’ rotates an input geometry around a base plane by a defined degree. + +* **Tense:** Don't use future tense (or any tense other than present, unless there's a reason to do so). + **Bad example:** ‘List.Sublists’ will take an input list and return a series of sublists based on the input range and offset. + +* **Numbers:** Don't spell out numbers when describing example files, unless the numbers are used to describe the graph layout, for example, "two nodes." + **Bad example:** In the example below, a simple loop is created to add ten, starting with one, until the result is larger than one hundred. diff --git a/.claude/skills/dynamo-content-designer/assets/node-errors-warnings.md b/.claude/skills/dynamo-content-designer/assets/node-errors-warnings.md new file mode 100644 index 00000000..12ebac7c --- /dev/null +++ b/.claude/skills/dynamo-content-designer/assets/node-errors-warnings.md @@ -0,0 +1,101 @@ +# Node errors and warnings + +Node warnings and errors alert the user to an issue with the graph. They notify the user of problems that interfere with normal graph operation by displaying an icon and expanded text bubble above the node. Node errors and warnings can vary in severity: Some graphs can run sufficiently with warnings, while others block expected results. In all cases, node errors and warnings are important tools to keep the user up to date on issues with their graph. + +Follow these guidelines to ensure consistency and help save time when writing or updating node warning and error messages. + +--- + +## Overview + +Node warnings and errors appear above nodes, and users must hover over them to read the issue text. They are different from modal warnings and errors, which appear as separate dialogs and prevent the user from advancing until they've interacted with the dialog. + +Since node warnings and errors indicate a problem with a graph, expect the user encountering them to feel blocked and frustrated, especially if the issue is unfamiliar or unexpected. Messaging should strive to help explain and resolve the issue as quickly and efficiently as possible. + +Language should be as clear and simple as possible. It should help minimize the need to leave Dynamo to ask for help from a colleague, forum member, or customer support. Be sure to explain: + +- What happened to cause the warning or error +- How to get back on track +- How to avoid the situation that triggered the warning or error in the future + +--- + +## Anatomy + +A node error/warning message can include up to 4 distinct sections: + +1. **Warning/error title**: Clearly state the warning. This should be an at-a-glance summary of the issue. Sentence case (capitalize only the first letter of the sentence and any proper nouns), 3-5 words, no end punctuation. +2. **Briefly explain issue**: Explain what most likely caused the message and what the implications are. Sentence case, 30 words max, normal sentence punctuation. +3. **Help resolve issue**: Provide advice on how to resolve the error or avoid it in the future. Sentence case, 35 words max, normal sentence punctuation. +4. **Help link**: Link to help documentation, if available. You can provide a more in-depth explanation, examples, and guidance in the expanded documentation. This should specifically be "Learn more" instead of any other variations. + +--- + +## Guidelines + +### Word choice + +**Do** + +- Use descriptive, clear, and concise language. As much as possible, imagine you are explaining the issue to a non-technical friend. + - Example: Empty value received + - Example: Unable to create PolyCurve. + +**Don't** + +- Don’t use jargon or highly advanced technical terms. More technical explanations can be provided in the expanded help. + - Bad example: Dereferencing a non-pointer + - Bad example: PolyCurve.ByPoints operation failed. + +--- + +### References to node names and input types + +**Do** + +- Minimize use of node names in running text when possible. When including node names and full input types improves clarity, use formatting to improve readability and reduce visual clutter. + - Example: The node received an input type it cannot use. + Input expected: Autodesk.DesignScript.Geometry.Curve + Input received: Function + + +**Don't** + +- Avoid using node names and full input types in running text. It reduces scannability and can be confusing to read. +- Bad example: Surface.ByPatch expects argument type(s)(Autodesk.DesignScript.Geometry.Curve), but was called with (Function). + +--- + +### Tone + +**Do** + +- Messaging should seek to calmly help the user solve the issue. Be succinct to help the user proceed. +- Example: Save your work and reload the graph. + +- Focus on explaining and resolving the issue, not identifying who's at fault. +- Example: Make sure the upstream nodes have non-empty values. +- Example: To create a PolyCurve, provide a non-empty list. + +**Don't** + +- Don't deviate from a professional tone or be needlessly verbose. +- Bad example: Giving the Dynamo VM a new lease of life can potentially make it feel happier and behave better. + +- Don't blame the user. Don't say "sorry." +- Bad example: You didn't provide an input. +- Bad example: Sorry, but we can't make a PolyCurve from an empty list. + +--- + +### Punctuation + +**Do** + +- To reinforce a calm, helpful tone, use periods at the end of sentences, or question marks for questions. +- Example: Unable to loft. + +**Don't** + +- Never "yell" at the user by using exclamation points. +- Bad example: Unable to loft! diff --git a/.claude/skills/dynamo-content-designer/assets/release-notes.md b/.claude/skills/dynamo-content-designer/assets/release-notes.md new file mode 100644 index 00000000..647cb1e0 --- /dev/null +++ b/.claude/skills/dynamo-content-designer/assets/release-notes.md @@ -0,0 +1,43 @@ +### Release notes + +Ensure that each release note is clear, concise, grammatically correct, and adheres to a neutral tone. The revised sentences should start with a past-tense verb and include all necessary articles. Do not use special characters, bolding, or italics. Avoid internal jargon, and explain all terminology so that the user can understand it. If you don’t know the meaning of some terms mentioned in the release notes, ask. + +**Good examples:** + +- Added support for view extensions to inject menu items into the File menu. +- Prevented Dynamo from loading packages from ProgramData when outdated settings were present. +- Ensured the Python migration toast notification closes when the graph is closed. +- Disabled sign-in functionality in no network mode. + +--- + +### Node descriptions + +Node descriptions briefly describe a node’s function and output. In Dynamo, they appear in two places: + +- In the node tooltip +- In the documentation browser + +Follow these guidelines to ensure consistency and help save time when writing or updating node descriptions. + +#### Overview + +Descriptions should be one to two sentences. If more info is needed, it can be included under In Depth in the Documentation Browser. + +Sentence case (capitalize the first word of a sentence and any proper nouns). No period at the end if the description is one sentence. Use a period at the end if the description is two or more sentences. + +Language should be as clear and simple as possible. Define acronyms at first mention unless they are known even to non-expert users. + +Always prioritize clarity, even if that means deviating from these guidelines. + +#### Guidelines + +| Do's | Don'ts | +|------|--------| +| Start the description with a third-person verb. Example: "Determines if one geometry object intersects with another" | Don't start with a second-person verb or with any noun. Bad example: "Determine if one geometry object intersects with another" | +| Use "Returns," "Creates," or another descriptive verb instead of "Gets." Example: "Returns a Nurbs representation of a surface" | Don't use "Get" or "Gets." It's less specific and has several possible translations. Bad example: "Gets a Nurbs representation of the surface" | +| When referring to inputs, use "given" or "input" instead of "specified." Example: "Deletes the given file." You may use "specified" when not directly referring to an input. Example: "Writes text content to a file specified by the given path" | Don't use "specified" when directly referring to inputs. Bad example: "Deletes the specified file" | +| Use "a" or "an" when first referring to an input. Use "the given" or "the input" for clarity. Example: "Sweeps a curve along the path curve" | Don't use "this" when first referring to an input. Bad example: "Sweeps this curve along the path curve" | +| Use "a" or "an" when first referring to an output. Use "the" only with "input" or "given." Example: "Copies a file. Copies the given file" | Don't use "the" on its own for outputs. Bad example: "Copies the file" | +| Capitalize the first word of a sentence and proper nouns. Example: "Returns the intersection of two BoundingBoxes" | Don't capitalize common geometry objects. Bad example: "Scales non-uniformly around the given Plane" | +| Capitalize Boolean, True, and False for output. Example: "Returns True if the two values are different" | Don't lowercase Boolean, True, or False. Bad example: "Returns true if the two values are different" | diff --git a/.claude/skills/dynamo-content-designer/assets/tutorials-user-guides.md b/.claude/skills/dynamo-content-designer/assets/tutorials-user-guides.md new file mode 100644 index 00000000..7e2da40e --- /dev/null +++ b/.claude/skills/dynamo-content-designer/assets/tutorials-user-guides.md @@ -0,0 +1,73 @@ +# Tutorials Template + +# Learn [Skill] by Building [Project] + +## What We're Building +[Visual/description of end result] +[Skills you'll learn] +[Prerequisites] + +## Step 1: [First Tangible Progress] +[Why this step matters] +[Code/commands] +[Verify it works] + +## Step 2: [Build on Previous] +[Connect to previous step] +[New concept introduction] +[Hands-on exercise] + +[Continue steps...] + +## Going Further +[Variations to try] +[Additional challenges] +[Related topics to explore] + +--- + +# User Guides Template + +# [Product/Feature] User Guide + +## Overview +**What is [Product]?**: [One sentence explanation] +**Who is this for?**: [Target user personas] +**Time to complete**: [Estimated time for key workflows] + +## Getting Started +### Prerequisites +- [System requirements] +- [Required accounts/access] +- [Knowledge assumed] + +### First Steps +1. [Most critical setup step with why it matters] +2. [Second critical step] +3. [Verification: "You should see..."] + +## Common Workflows + +### [Primary Use Case 1] +**Goal**: [What user wants to accomplish] +**Steps**: +1. [Action with expected result] +2. [Next action] +3. [Verification checkpoint] + +**Tips**: +- [Shortcut or best practice] +- [Common mistake to avoid] + +### [Primary Use Case 2] +[Same structure as above] + +## Troubleshooting +| Problem | Solution | +|---------|----------| +| [Common error message] | [How to fix with explanation] | +| [Feature not working] | [Check these 3 things...] | + +## FAQs +**Q: [Most common question]?** +A: [Clear answer with link to deeper docs if needed] diff --git a/.claude/skills/dynamo-content-designer/assets/ui-content.md b/.claude/skills/dynamo-content-designer/assets/ui-content.md new file mode 100644 index 00000000..e0431705 --- /dev/null +++ b/.claude/skills/dynamo-content-designer/assets/ui-content.md @@ -0,0 +1,109 @@ +# UI Content + +User interface content is a cornerstone of our products. Our word choices affect how a product is used, and how a product is used affects our word choices. + +Creating high-quality content takes more than just good writing. In addition, text strings must be actionable, consistent, and presented so that users can accomplish their tasks as quickly as possible. + +UI content can include: + +- Error messages +- Notifications +- Labels +- Tooltips + +## Guidelines for Writing UI Content + +### 1. Clarity over Complexity + +**Simplify complexity without losing meaning.** + +**Why it matters** +Clarity is more important than brevity. Clear and concise content reduces cognitive load and frustration, and helps people complete tasks faster. + +**What it drives** +Ease of use + +**How to apply it** + +- Use plain language, break down complex workflows into manageable steps, and remove unnecessary jargon +- Prioritize understanding over technical detail +- Don't assume people understand technical terms + +### 2. Helpful and Actionable + +**Guide users toward action and success.** + +**Why it matters** +Usable is more important than being technically precise. Content should help people complete tasks efficiently. + +**What it drives** +Speed + +**How to apply it** + +- Design for maximum usability and accessibility +- Ensure people always know what to do next +- Use progressive disclosure and show essential content first, giving options to see more details if needed +- Use content patterns and terminology consistently across all touch points + +### 3. Trustworthy and Transparent + +**Be transparent and show empathy for people's goals and frustrations.** + +**Why it matters** +Long term trust wins over short-term gain. Transparent communication reduces friction and builds positive relationships with people. + +**What it drives** +Trust + +**How to apply it** + +- Use supportive language +- Offer solutions and make people feel in control and that their goals are being prioritized + +#### Build and Maintain Trust + +- Give users clear choices and control +- Be transparent about data use and product behavior +- Use a consistent and reliable voice across the product + +#### Be Clear and Concise + +- Keep content brief, scannable, and to the point +- Use visual hierarchy to guide attention, such as headers +- Write only what's necessary—every word should support the user experience + +#### Design for the User + +- Use plain language and limit jargon +- If technical terms are necessary, use them only when they aid clarity +- Avoid internal terminology that users won't understand + +### 4. Use Active, Direct Language + +- Use active voice over passive unless it's to quickly summarize an event +- Speak directly to users using "you" and "your" +- Minimize first-person usage unless taking ownership or making a clear commitment + +**Exception for passive voice** +Use passive voice to quickly summarize an event when needed. + +### 5. Trust the UX + +- Don't add content if the design communicates effectively on its own +- Simplify whenever possible to reduce cognitive load + +### 6. Guide Proactively + +- Know the user's flow and provide content that supports it at each step +- Use progressive disclosure—give the right information at the right time, and reveal more as needed +- Start with what matters most (the "why"), then explain the "how" + +### 7. Design for Accessibility and Inclusivity + +- Follow or exceed WCAG AA standards +- Use inclusive, respectful language that considers all users +- Keep language simple and clear for global audiences +- Aim for a Flesch-Kincaid readability score of 70–80, or grade level 7–8 +- Avoid idioms, clichés, slang, or region-specific phrases +- Improve clarity by using simple language that supports localization for non-native English speakers