Dynamo Content Designer

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.

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.