• Best Practices

    Guidelines for writing effective, maintainable Chalk content.

    Content Structure

    Use Clear Headings

    ## Main Topic
### Subsection
#### Specific Point
    • Use descriptive, action-oriented headings
    • Keep heading hierarchy logical
    • Don’t skip heading levels

    Organize Content Logically

    1. Start with an overview or introduction
    2. Present concepts in order of complexity
    3. Include examples and demonstrations
    4. End with practice or reflection

    Writing Style

    Be Clear and Concise

    • Write in active voice
    • Use simple, direct language
    • Break complex concepts into digestible chunks
    • Include examples to illustrate points

    Use Consistent Formatting

    • Use bold for emphasis on key terms
    • Use ==highlight== for important concepts
    • Use code for technical terms and commands
    • Use Keystrokes for keyboard shortcuts

    Embeds and Media

    Image Best Practices

    !!!
screenshot.png
[User interface showing the login form with email and password fields]
The login form includes email and password fields with clear labels.
!!!
    • Always include descriptive alt text
    • Use captions to explain context and purpose
    • Keep file sizes reasonable (under 1MB when possible)
    • Use appropriate formats (PNG for screenshots, SVG for icons)

    Interactive Components

    • Keep components focused and single-purpose
    • Test components thoroughly before including
    • Provide clear instructions for interaction
    • Consider loading performance

    Prompts and Quizzes

    Effective Prompts

    ???
Think about a website you use regularly.
What visual elements help you understand how to navigate?
???
    • Ask open-ended questions that encourage reflection
    • Connect to real-world experiences
    • Provide enough context for meaningful responses
    • Avoid yes/no questions when possible

    Quiz Design

    ???
What is the primary purpose of wireframes?

[ ] To create final visual designs
Wireframes focus on structure, not visual design.

[x] To plan layout and user flow
Correct! Wireframes help plan the structure and flow.

[ ] To write content
Content planning happens separately from wireframing.
???
    • Include feedback for each answer option
    • Use distractors that represent common misconceptions
    • Keep questions focused on one concept
    • Provide clear, helpful feedback

    File Organization

    Naming Conventions

    • Use descriptive, lowercase filenames with hyphens
    • Include numbers for ordering: 01-introduction.chalk
    • Group related content in folders
    • Keep media files close to their content

    Structure Guidelines

    lesson/
├── index.chalk
├── 01-concept.png
├── 02-demo.mp4
└── 03-practice.chalk

    Accessibility

    Alt Text Guidelines

    • Describe the content and purpose, not just what you see
    • Be concise but informative
    • Don’t start with “Image of…” or “Picture of…”
    • Include important text that appears in images

    Content Accessibility

    • Use proper heading hierarchy
    • Write clear, descriptive link text
    • Provide text alternatives for complex visual content
    • Test with screen readers when possible

    Performance Considerations

    Media Optimization

    • Compress images before embedding
    • Use appropriate formats (WebP for photos, SVG for graphics)
    • Consider lazy loading for large media files
    • Keep video files reasonably sized

    Component Performance

    • Keep interactive components lightweight
    • Avoid unnecessary dependencies
    • Test loading times on slower connections
    • Consider progressive enhancement

    Version Control

    Commit Messages

    • Use descriptive commit messages
    • Reference issue numbers when applicable
    • Group related changes in single commits
    • Test content before committing

    Content Review

    • Review content for accuracy and clarity
    • Check all links and embeds work correctly
    • Verify syntax is correct
    • Test interactive components