Task Descriptions with Rich Text
A task title tells you *what* needs to be done, but a well-crafted description explains *why*, *how*, and *what success looks like*. Waymaker's rich text editor transforms task descriptions from plain text notes into comprehensive documentation with formatting, structure, and visual elements.
Task Descriptions with Rich Text
Difficulty: Beginner to Intermediate
Overview
A task title tells you what needs to be done, but a well-crafted description explains why, how, and what success looks like. Waymaker's rich text editor transforms task descriptions from plain text notes into comprehensive documentation with formatting, structure, and visual elements.
Whether you're documenting technical requirements for developers, outlining marketing campaign details for creatives, or specifying acceptance criteria for client deliverables, mastering rich text descriptions ensures your team has the context they need to succeed.
What You'll Learn
- Navigate and use the rich text editor toolbar effectively
- Apply text formatting for emphasis and clarity
- Structure content with headings and hierarchical organization
- Create various list types including interactive checklists
- Insert and manage hyperlinks to external resources
- Embed images directly in task descriptions
- Format code blocks for technical documentation
- Build tables for structured data presentation
- Understand auto-save behavior and manual saving
- Follow best practices for clear, actionable descriptions
Prerequisites
- Active Waymaker organization account
- Access to a taskboard (member role or higher)
- Basic familiarity with creating and editing tasks
- Understanding of task detail view navigation
Accessing the Rich Text Editor
The rich text editor appears in the task description section:
Opening the Editor:
- Open any task (click task card or create new task)
- Locate the "Description" section in the task detail view
- Click into the description area to activate the editor
- Toolbar appears at the top of the editing area
Editor Interface:
- Toolbar: Formatting buttons and options
- Editing Area: Main content workspace (expandable)
- Status Indicator: Auto-save status in bottom right
- Preview Mode: Toggle to see rendered output (some editors)
Keyboard Shortcut:
- Press
Tabfrom task name field to jump to description - Press
Escto exit description and save changes
Rich Text Editor Toolbar
The toolbar provides quick access to all formatting capabilities. Let's explore each section from left to right:
Text Formatting Section
Bold:
- Button: B icon
- Shortcut: Cmd/Ctrl + B
- Usage: Emphasize key points, terms, or important information
- Markdown:
**bold text**
Italic:
- Button: I icon
- Shortcut: Cmd/Ctrl + I
- Usage: Subtle emphasis, foreign words, book titles
- Markdown:
*italic text*
Underline:
- Button: U icon
- Shortcut: Cmd/Ctrl + U
- Usage: Highlight specific terms (use sparingly)
- Note: Not standard markdown, editor-specific
Strikethrough:
- Button: S with line through it
- Shortcut: Cmd/Ctrl + Shift + X
- Usage: Show removed or deprecated content
- Markdown:
~~strikethrough text~~
Combining Formats: You can combine multiple formats:
***Bold and italic***
**~~Bold strikethrough~~**
***~~All three combined~~***
Best Practice: Use formatting sparingly for maximum impact. Too much emphasis becomes noise.
Heading Levels
Headings create hierarchical structure and scannable content.
Available Levels:
- H1: Main topic heading (largest)
- H2: Major sections
- H3: Subsections
- H4-H6: Further nesting (available in some editors)
Accessing Headings:
- Dropdown menu labeled "Normal" or "Paragraph"
- Select desired heading level
- Or use markdown:
# H1,## H2,### H3
Heading Hierarchy Example:
## Context
Background information about this task.
## Requirements
What needs to be accomplished.
### Functional Requirements
Specific features and behaviors.
### Non-Functional Requirements
Performance, security, accessibility needs.
## Acceptance Criteria
How we know it's done.
Visual Impact: Headings appear larger and bolder than normal text, creating clear visual breaks and scannable structure.
Accessibility Note: Proper heading hierarchy helps screen readers navigate content. Don't skip levels (don't jump from H2 to H4).
Lists and Checklists
Lists organize information and make content easier to scan.
Bulleted Lists
Creating Bullet Lists:
- Click bullet list button (three stacked dots)
- Or type
*,-, or+followed by space - Press Enter to create next item
- Press Enter twice to exit list
Nested Lists:
* Main item 1
* Sub-item 1a
* Sub-item 1b
* Main item 2
* Sub-item 2a
* Sub-sub-item 2a-i
When to Use:
- Listing features or requirements
- Outlining steps without specific order
- Brainstorming ideas
- Listing resources or links
Numbered Lists
Creating Numbered Lists:
- Click numbered list button (1, 2, 3 icon)
- Or type
1.followed by space - Numbers auto-increment
- Press Enter to add next item
Nested Numbered Lists:
1. First main step
1. Sub-step A
2. Sub-step B
2. Second main step
1. Sub-step A
2. Sub-step B
When to Use:
- Sequential steps or procedures
- Prioritized lists
- Instructions with specific order
- Acceptance criteria ranked by importance
Interactive Checklists
Creating Checklists:
- Click checkbox list button (box with checkmark)
- Or type
- [ ]or* [ ]followed by space - Click checkboxes to mark complete
- Checked items appear with strikethrough or checkmark
Checklist Example:
## Acceptance Criteria
- [ ] User can log in with email and password
- [ ] Error messages appear for invalid credentials
- [ ] "Remember me" checkbox functions correctly
- [ ] Password reset link is functional
- [ ] Login works on mobile devices
Interactive Features:
- Click checkboxes directly in rendered view
- Completion tracked and saved
- Some boards show checklist progress (3/5 items complete)
- Can drive task progress percentage (if enabled)
Checklists vs Separate Tasks:
Use checklists when:
- Items are part of a single larger task
- No individual assignment needed
- Quick completion tracking sufficient
- Items don't need their own due dates
Create separate tasks when:
- Items assigned to different people
- Each needs individual due dates
- Separate time tracking required
- Items are substantial work efforts
For more on this decision, see: Task Checklists and Subtasks
Links and Hyperlinks
Links connect tasks to external resources, documentation, and related content.
Creating Hyperlinks
Method 1: Toolbar Button
- Select text to be linked
- Click link button (chain icon)
- Paste URL in dialog
- Click "Insert" or press Enter
Method 2: Markdown Syntax
[Link text](https://example.com)
[Waymaker Documentation](https://docs.waymakerone.com)
Method 3: Paste URL Some editors auto-detect URLs and create clickable links:
https://waymakerone.com
Link Best Practices
Descriptive Link Text:
✅ Good: [View design mockups in Figma](https://figma.com/...)
✅ Good: Review the [API documentation](https://docs.example.com)
❌ Bad: [Click here](https://example.com)
❌ Bad: [Link](https://example.com)
Organize with Sections:
## Resources
- **Design:** [Figma mockups](https://figma.com/...)
- **Documentation:** [API reference](https://docs.example.com)
- **Related Tasks:** [See task #245](#245)
## External References
- [Competitor example](https://competitor.com)
- [Industry best practices](https://bestpractices.org)
Link Maintenance:
- Verify links aren't broken (especially for external resources)
- Update links when resources move
- Remove outdated links promptly
- Use permanent links when available (avoid "latest" or "current")
Internal Task Links
Linking to Other Tasks: Many systems support referencing other tasks:
Blocked by task #123
Depends on #456 and #789
See also: #234 for related work
Benefits:
- Click to navigate directly to referenced task
- Visual indication of task relationships
- Easier than formal dependency management for loose coupling
Note: This differs from formal task dependencies, which enforce scheduling rules. Internal links are for reference only.
Images in Descriptions
Visual elements enhance understanding, especially for design tasks, bug reports, and documentation.
Inserting Images
Method 1: Upload from Computer
- Click image button in toolbar (picture icon)
- Click "Upload" or drag image into dialog
- Select image file (PNG, JPG, GIF, SVG)
- Image uploads and embeds automatically
Method 2: Drag and Drop
- Drag image file from desktop
- Drop directly into description editor
- Image uploads and embeds at cursor position
Method 3: Paste from Clipboard
- Copy image (screenshot, etc.)
- Click in description editor
- Paste (Cmd/Ctrl + V)
- Image uploads and embeds automatically
Method 4: Link to External Image
Image Management
Supported Formats:
- PNG (best for screenshots, UI mockups)
- JPG/JPEG (best for photos)
- GIF (simple animations)
- SVG (vector graphics, icons)
- WebP (modern, efficient format)
File Size Limits:
- Maximum file size: 10MB per image (typical)
- Recommend keeping images under 2MB for performance
- Compress large screenshots before uploading
Image Optimization Tips:
- Crop unnecessary content before uploading
- Use PNG for screenshots (better quality)
- Use JPG for photos (smaller file size)
- Compress images with tools like TinyPNG
- Resize to reasonable dimensions (max 2000px wide)
Alt Text for Accessibility: Always include descriptive alt text:
Screen readers announce alt text to visually impaired users.
Image Use Cases
Bug Reports:
## Bug Description
Login button doesn't work on mobile Safari.
## Screenshot
## Expected Appearance
Design Tasks:
## Design Reference
Recreate this navigation pattern:
## Current State
Documentation:
## Process Flow
1. User enters email
2. System sends verification
3. User confirms email
4. Account activated
Code Blocks for Technical Tasks
Code blocks preserve formatting and provide syntax highlighting for technical content.
Creating Code Blocks
Inline Code: For short code snippets or commands:
Run the `npm install` command to install dependencies.
Update the `config.json` file with your API key.
Renders as: Run the npm install command to install dependencies.
Multi-Line Code Blocks:
Method 1: Toolbar Button
- Click code block button (<> icon)
- Paste or type code
- Select language for syntax highlighting
Method 2: Markdown Syntax Use triple backticks with optional language:
```javascript
function calculateTotal(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}
**Language Support:**
Common languages with syntax highlighting:
- `javascript`, `typescript`
- `python`, `ruby`, `php`
- `html`, `css`, `scss`
- `json`, `yaml`, `xml`
- `sql`, `bash`, `shell`
- `markdown`
### Code Block Best Practices
**Include Context:**
```markdown
## Implementation Notes
Update the authentication function in `auth.js`:
```javascript
// Add session timeout check
function validateSession(token) {
const session = decodeToken(token);
if (Date.now() > session.expiresAt) {
throw new SessionExpiredError();
}
return session;
}
**Add Comments:**
Explain complex or important lines:
```javascript
// Check if user has admin privileges
if (user.role === 'admin' && user.permissions.includes('delete')) {
// Allow deletion of any resource
return true;
}
Show Before/After:
## Change Required
**Before:**
```javascript
const total = items.length;
After:
const total = items.reduce((sum, item) => sum + item.quantity, 0);
**Command Examples:**
```markdown
## Setup Instructions
1. Clone repository:
```bash
git clone https://github.com/example/repo.git
cd repo
- Install dependencies:
npm install
- Start development server:
npm run dev
## Tables for Structured Data
Tables organize information in rows and columns, perfect for specifications, comparisons, or structured requirements.
### Creating Tables
**Markdown Table Syntax:**
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | More |
| Row 2 | Data | More |
Alignment:
| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left | Center | Right |
Toolbar Table Builder: Some rich text editors include table builder:
- Click table button
- Select rows and columns
- Click to insert
- Fill in content
Table Use Cases
Specifications:
## API Endpoints
| Endpoint | Method | Description | Auth Required |
|----------|--------|-------------|---------------|
| /users | GET | List all users | Yes |
| /users/:id | GET | Get user details | Yes |
| /users | POST | Create new user | Admin only |
| /users/:id | PUT | Update user | Yes |
| /users/:id | DELETE | Delete user | Admin only |
Requirements Matrix:
## Browser Support
| Browser | Minimum Version | Fully Supported | Notes |
|---------|----------------|-----------------|-------|
| Chrome | 90+ | ✅ | Primary target |
| Firefox | 88+ | ✅ | Full support |
| Safari | 14+ | ⚠️ | Some CSS issues |
| Edge | 90+ | ✅ | Chromium-based |
| IE 11 | - | ❌ | Not supported |
Comparison Tables:
## Design Options
| Option | Pros | Cons | Effort |
|--------|------|------|--------|
| Sidebar nav | Familiar, more space | Requires click | 3 days |
| Top nav | Always visible | Limited space | 2 days |
| Hybrid | Best of both | More complex | 5 days |
Test Cases:
## Test Scenarios
| Scenario | Input | Expected Output | Status |
|----------|-------|-----------------|--------|
| Valid login | correct credentials | redirect to dashboard | ✅ Pass |
| Invalid password | wrong password | error message shown | ✅ Pass |
| Empty fields | no input | validation error | ❌ Fail |
| SQL injection | malicious input | sanitized, rejected | ⏳ Pending |
Table Tips
- Keep tables simple (max 5-6 columns for readability)
- Use abbreviated headers if full names are too long
- Include units in column headers (Time (hours), Cost ($))
- Use emojis for visual indicators (✅ ❌ ⚠️ ⏳)
- Consider lists for single-column data
Auto-Save and Manual Saving
Understanding save behavior prevents lost work and confusion.
Auto-Save Functionality
How Auto-Save Works:
- Triggers after brief pause in typing (typically 2-3 seconds)
- Saves in background without interrupting editing
- Status indicator shows "Saving..." then "Saved"
- No need to click save button for most edits
What Triggers Auto-Save:
- Typing pauses
- Switching between fields
- Clicking outside editor
- Applying formatting
- Inserting images or links
Auto-Save Indicator: Look for status in bottom-right of editor:
- ⏺ "Typing..." - Active editing
- 💾 "Saving..." - Save in progress
- ✅ "Saved" - Changes persisted
Network Requirements: Auto-save requires internet connection:
- Works over slow connections (saves queued)
- Offline changes stored locally
- Syncs when connection restored
Manual Saving
When to Manually Save: Most editors auto-save, but manual save ensures:
- Immediate persistence before closing
- Confirmation of changes saved
- Explicit save point before major edits
How to Manually Save:
- Click "Save" button (if present)
- Use keyboard shortcut: Cmd/Ctrl + S
- Click outside task detail modal (triggers save)
Save Confirmation: After manual save:
- "Saved successfully" message appears
- Updated timestamp shown
- Modal can be safely closed
Version History
Change Tracking: Task descriptions are versioned:
- Each save creates history entry
- View previous versions in activity feed
- Revert to earlier version if needed
- See who made each change and when
Accessing Version History:
- Open task detail
- Navigate to "Activity" tab
- Filter for "description changed" events
- Click event to see old vs new content
- Option to restore previous version (if available)
Formatting Best Practices
Creating Scannable Content
Use Hierarchy:
## Main Section (H2)
Overview paragraph.
### Subsection (H3)
Detailed content.
#### Detail Point (H4)
Specific information.
Short Paragraphs: Break long paragraphs into 3-4 line chunks for easier scanning.
Bullet Points: Transform dense paragraphs into scannable lists:
❌ Before:
This task requires updating the user profile page with new fields including phone number, company name, and job title, as well as adding validation for email format, ensuring the phone number uses international format, and implementing autosave functionality.
✅ After:
## Requirements
- Add new profile fields:
- Phone number (international format)
- Company name
- Job title
- Implement validation:
- Email format checking
- Phone number formatting
- Add autosave functionality
Emphasis Hierarchy
Use formatting levels purposefully:
Level 1 - Bold: Most important points
**Critical:** This must be completed before launch.
Level 2 - Italic: Secondary emphasis
*Note:* This is a nice-to-have feature.
Level 3 - Regular text: Standard information
Avoid:
- ALL CAPS (appears shouty)
- Excessive underlining (looks like links)
- Multiple exclamation marks!!!
Consistent Formatting
Establish Patterns: All tasks in your board should use similar structure:
## Context
Why this task exists.
## Requirements
What needs to be done (bulleted list).
## Acceptance Criteria
- [ ] Checklist of success criteria
## Resources
- [Links to relevant documents]
## Notes
Additional information.
Template Usage: Create description templates for recurring task types:
- Bug reports
- Feature requests
- Content creation
- Client deliverables
- Research tasks
For more on templates, see: Board Templates and Reusability
Description Templates
Bug Report Template
## Bug Description
[Concise description of the issue]
## Steps to Reproduce
1. [Step one]
2. [Step two]
3. [Step three]
## Expected Behavior
[What should happen]
## Actual Behavior
[What actually happens]
## Screenshots
## Environment
- **Browser:** [Chrome 96, Firefox 94, etc.]
- **OS:** [Windows 11, macOS 12, etc.]
- **Version:** [Application version]
- **User Role:** [Admin, Member, etc.]
## Additional Context
[Any other relevant information]
## Priority Justification
[Why this priority level was assigned]
User Story Template
## User Story
**As a** [type of user]
**I want** [goal/desire]
**So that** [benefit/value]
## Acceptance Criteria
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]
## Design Resources
- **Mockups:** [Figma link]
- **Prototype:** [InVision link]
- **Style Guide:** [Link to design system]
## Technical Considerations
[Implementation notes, potential challenges]
## Definition of Done
- [ ] Code written and reviewed
- [ ] Unit tests passing
- [ ] Integration tests passing
- [ ] Documentation updated
- [ ] Deployed to staging
- [ ] QA approved
- [ ] Product owner approved
Research Task Template
## Research Question
[What we need to learn or investigate]
## Context
[Why this research matters, background]
## Research Goals
- [Goal 1]
- [Goal 2]
- [Goal 3]
## Methodology
[How the research will be conducted]
## Resources
- [Existing research or documentation]
- [Tools or platforms to use]
## Deliverable
[What output is expected]
- [ ] Research summary document
- [ ] Presentation to team
- [ ] Recommendation with rationale
## Success Criteria
[How we'll know the research is complete and valuable]
Tips & Best Practices
Writing Effective Descriptions
- Front-load important information (people skim)
- Use active voice and action verbs
- Be specific and concrete, avoid vague language
- Include "why" not just "what" and "how"
- Link to external resources rather than duplicating content
- Update descriptions as requirements evolve
Formatting for Your Audience
- Developers: Code blocks, technical specs, API links
- Designers: Images, visual examples, brand guidelines
- Writers: Style guides, voice/tone notes, examples
- Executives: Business context, ROI, strategic alignment
- Clients: Clear deliverables, approval criteria, timelines
Maintenance
- Review and update descriptions when scope changes
- Archive completed tasks with final notes
- Remove outdated screenshots or broken links
- Standardize formatting across related tasks
- Create templates for recurring task types
Collaboration
- Write for someone who isn't you (future self or teammate)
- Include enough context for new team members
- Document decisions and rationale
- Use comments for discussion, description for facts
- Keep descriptions focused, use comments for back-and-forth
Common Mistakes to Avoid
Over-Formatting
Mistake: Every word bold, italic, or underlined. Solution: Use formatting sparingly for actual emphasis. Too much formatting is visual noise.
Wall of Text
Mistake: Dense paragraphs without structure or breaks. Solution: Use headings, lists, and short paragraphs. Make content scannable.
No Visual Elements
Mistake: Pure text descriptions for visual tasks. Solution: Include screenshots, mockups, diagrams, or examples. Show, don't just tell.
Broken Links
Mistake: Links to moved resources or outdated documentation. Solution: Verify links when creating. Review and update periodically.
Vague Acceptance Criteria
Mistake: "Make it look good" or "Fix the bugs." Solution: Specific, measurable, testable criteria. Define what "done" means.
Ignoring Templates
Mistake: Every task described differently, inconsistent structure. Solution: Use templates for recurring task types. Standardize sections.
Forgetting to Save
Mistake: Making changes and closing without saving (in editors without auto-save). Solution: Save manually (Cmd/Ctrl + S) or wait for auto-save confirmation before closing.
Image Overload
Mistake: Embedding dozens of large images, slowing load time. Solution: Compress images, use thumbnails, or link to image galleries for many visuals.
Advanced Formatting Techniques
Combining Elements
Create rich, informative descriptions by combining formatting types:
## Implementation Plan
### Phase 1: API Development
**Timeline:** 2 weeks
**Owner:** Backend team
```javascript
// New endpoint structure
app.post('/api/users', authenticateUser, validateInput, createUser);
Requirements:
- JWT authentication working
- Input validation with Joi
- Error handling middleware
- Unit tests (80% coverage)
Resources:
Phase 2: Frontend Integration
Timeline: 1 week Owner: Frontend team
| Component | Status | Notes |
|---|---|---|
| Login form | ✅ Complete | Needs styling |
| Signup form | ⏳ In Progress | Awaiting API |
| Profile page | 📝 Planned | Design ready |
### Collapsible Sections
Some markdown editors support collapsible sections (details/summary):
```markdown
<details>
<summary>Click to see detailed technical notes</summary>
## Database Schema Changes
```sql
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
ALTER TABLE users ADD COLUMN company VARCHAR(100);
These changes require migration script and backward compatibility.
```Embedded Media
Link to or embed external content:
## Reference Video
Watch the [demo recording](https://vimeo.com/example) showing expected behavior.
## Design Files
- [Figma prototype](https://figma.com/file/example) (interactive)
- [Zeplin specs](https://zeplin.com/project/example) (developer handoff)
Related Articles
Task Management Basics
- Basic Task Management - Creating and editing tasks
- Task Details and Metadata - Complete field reference
- Task Checklists and Subtasks - Breaking down work
Content Creation
- Writing Effective Tasks - Task documentation best practices
- Board Templates and Reusability - Reusable task templates
Collaboration
- Task Comments and Activity Feed - Discussion vs documentation
- Team Collaboration Best Practices - Working together
Need More Help?
Additional Resources
- Video Tutorial: "Rich Text Editor Walkthrough" (10 minutes)
- Template Library: Download task description templates
- Markdown Guide: Complete markdown syntax reference
Contact Support
- Help Center: Browse common questions and solutions
- Email Support: support@waymakerone.com
- Live Chat: Available Monday-Friday, 9 AM - 5 PM EST
- Community Forum: Connect with other Waymaker users
Next Steps
- Practice with rich text formatting in a test task
- Create description templates for your common task types
- Review existing tasks and improve descriptions
- Train team members on formatting standards
- Establish team conventions for description structure
Well-formatted task descriptions are the foundation of effective collaboration. Invest time in creating clear, comprehensive descriptions, and your team will execute more confidently and efficiently.