• 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

    Multi-page sections

    When a folder has an index.chalk plus child pages:

    • Keep the parent light. The index should be a short description or brief intro. Chalk automatically adds a table of contents of child pages below—don’t dump the full document on the parent or hand-build a TOC that duplicates it.
    • Use short child titles. Frontmatter title is the sidebar/tree label. Prefer Product Brief or Competitive Landscape, not CSS Craft for Designers — Product Brief. The folder (or parent index title) already carries the topic name.
    • Order with filename prefixes. Prefer 1-product-brief.chalk, 2-competitive-landscape.chalk (or 01- / 02-) so TOC and tree order are explicit—same idea as Organizing Files.
    • Link with page names. See Inline links below.

    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

    Inline links

    Prefer link text that matches the page title or reads as natural prose—not the filename or path slug.

    <!-- Prefer -->
See the [Competitive Landscape](2-competitive-landscape.chalk) for positioning detail.
Building on the [Async-First Course Exploration](../async-course-exploration/).

<!-- Avoid -->
See [2-competitive-landscape.chalk](2-competitive-landscape.chalk).
See [async-course-exploration](../async-course-exploration/).
    • Use the name of the page being referred to when one exists
    • Use appropriate inline phrasing when a full title would be awkward (“the product brief”)
    • Keep the URL/path correct; only the visible label needs to be human-readable

    Content Accessibility

    • Use proper heading hierarchy
    • Write clear, descriptive link text (see Inline links)
    • 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