Skip to content

graph-creation.md

Latest commit

 

History

History
377 lines (289 loc) · 12.4 KB

graph-creation.md

File metadata and controls

377 lines (289 loc) · 12.4 KB
Raw

GraphDone Graph Creation Workflow

This guide covers the complete user journey for creating and managing graphs in GraphDone, from initial concept to collaborative execution.

Graph Creation Overview

GraphDone uses a graph-first approach where work items exist as connected nodes in a visual network. Each graph represents a workspace, project, or domain area where teams coordinate their efforts.

Getting Started

Prerequisites

  • Valid GraphDone account with appropriate permissions
  • Access to GraphDone web interface at http://localhost:3127 (dev) or https://localhost:3128 (prod)
  • Basic understanding of graph concepts (nodes, edges, relationships)

Step 1: Creating a New Graph

Access Graph Creation

  1. Login to GraphDone with your credentials
  2. Navigate to the workspace dashboard
  3. Click "Create New Graph" or use the "+" button in the graph selector
  4. Choose creation method:
    • From Template - Start with predefined structure
    • Blank Graph - Begin with empty canvas
    • Import - Load existing data

Graph Configuration

Basic Information:

  • Name: Descriptive title for your graph (e.g., "Mobile App Redesign")
  • Description: Detailed explanation of scope and purpose
  • Type: Select from available graph types:
    • PROJECT - Focused initiative with defined scope
    • WORKSPACE - Broader collaboration area
    • SUBGRAPH - Component of larger graph
    • TEMPLATE - Reusable pattern for other graphs

Access Control:

  • Visibility: Public, Private, or Team-specific
  • Permissions: Who can view, edit, and admin
  • Collaboration Settings: External access and sharing options

Initial Settings:

  • Default Priority Model: Individual, Community, or Executive-driven
  • Node Types: Enabled work item categories
  • Workflow States: Available status transitions

Step 2: Adding Your First Nodes

Node Creation Process

Quick Node Creation:

  1. Right-click on empty graph space
  2. Select "Add Work Item" from context menu
  3. Choose node type from comprehensive list
  4. Fill essential information and save

Detailed Node Creation:

  1. Click primary "Add Work Item" button

  2. Complete the node creation form:

    Essential Fields:

    • Title: Brief, descriptive name
    • Type: Choose from 60+ node types (TASK, EPIC, BUG, FEATURE, etc.)
    • Description: Detailed explanation
    • Status: Current state (NOT_STARTED, IN_PROGRESS, COMPLETED, etc.)

    Priority Configuration:

    • Executive Priority (0-1): Strategic importance
    • Individual Priority (0-1): Personal importance
    • Community Priority (0-1): Peer validation (starts at 0)

    Advanced Options:

    • Contributors: Assign team members
    • Metadata: Custom fields and tags
    • Estimated Effort: Time/complexity estimates

Node Types Reference

GraphDone supports 9 core node types designed for clarity and simplicity:

Core Types:

  • DEFAULT - Generic work item for uncategorized content
  • EPIC - Large initiative spanning multiple deliverables
  • MILESTONE - Key project checkpoint and important deadline
  • OUTCOME - Expected result or deliverable
  • FEATURE - New functionality or capability to be developed
  • TASK - Specific work item to be completed
  • BUG - Software defect requiring resolution
  • IDEA - Concept or proposal for future development
  • RESEARCH - Investigation or analysis work

Each node type has its own visual identity with distinct colors and icons in the interface.

Step 3: Creating Relationships

Edge Types and Meanings

GraphDone supports rich relationship modeling with 13 edge types:

Dependency Relationships:

  • DEPENDS_ON - Node requires completion of another
  • BLOCKS - Node prevents progress on another
  • ENABLES - Node makes another possible

Structural Relationships:

  • IS_PART_OF - Parent-child hierarchy
  • CONTAINS - Grouping and composition
  • FOLLOWS - Sequential ordering

Operational Relationships:

  • RELATES_TO - General association
  • PARALLEL_WITH - Concurrent execution
  • DUPLICATES - Same work as another node
  • CONFLICTS_WITH - Incompatible goals
  • VALIDATES - One node verifies another
  • REFERENCES - Citation or dependency reference

Creating Connections

Visual Connection:

  1. Click and hold on source node
  2. Drag to target node
  3. Release to create connection
  4. Select relationship type from popup
  5. Confirm to establish edge

Contextual Connection:

  1. Right-click on source node
  2. Select "Add Relationship"
  3. Choose target node from list or search
  4. Select relationship type
  5. Set optional weight/strength (0-1)

Relationship Editor:

  • Access via node details panel
  • Modify existing relationships
  • Bulk operations for multiple connections
  • Relationship validation prevents cycles

Step 4: Priority and Positioning

Understanding the Priority System

GraphDone uses multi-dimensional priority that determines node position in 3D spherical space:

Priority Components:

  • Executive Priority: Top-down strategic importance
  • Individual Priority: Bottom-up personal investment
  • Community Priority: Peer validation and boosting

Computed Priority: Weighted combination determines:

  • Spherical Position: Distance from center (radius)
  • Resource Allocation: Closer nodes get more resources
  • Visibility: Central nodes more prominently displayed

Priority Manipulation

Setting Initial Priority:

  • Configure during node creation
  • Executive/Individual set by creator
  • Community priority starts at 0

Community Boosting:

  • Anonymous rating system prevents bias
  • Click boost button to increase community priority
  • Boost amount configurable per organization
  • Cumulative effect drives nodes toward center

Dynamic Updates:

  • Priority changes trigger real-time position updates
  • Smooth animations show priority migration
  • Visual feedback indicates boost received

Step 5: Collaborative Features

Team Coordination

Contributor Assignment:

  • Assign team members to specific nodes
  • Role specification: Owner, Contributor, Reviewer
  • Workload balancing across team members
  • Notification system for assignments

Real-Time Collaboration:

  • Live updates as team members make changes
  • Conflict resolution for simultaneous edits
  • Activity feed showing recent changes
  • Presence indicators for active collaborators

Communication Features

Node Comments:

  • Threaded discussions on individual nodes
  • @mention notifications for team members
  • Comment history and audit trail
  • Rich text formatting and attachments

Status Updates:

  • Progress tracking through status transitions
  • Automated notifications on status changes
  • Blocking indicators for dependent work
  • Completion celebrations and team recognition

Step 6: Graph Views and Navigation

Available View Modes

Graph View (Primary):

  • Interactive 3D visualization with physics simulation
  • Zoom and pan for detailed inspection
  • Filter controls for node types and status
  • Layout algorithms for optimal arrangement

Table View:

  • Spreadsheet-style data representation
  • Sortable columns for all node properties
  • Bulk editing capabilities
  • Export functionality for external tools

Kanban Board:

  • Status-based columns for workflow management
  • Drag-and-drop status transitions
  • WIP limits and flow optimization
  • Sprint/iteration organization

Gantt Chart:

  • Timeline visualization of dependencies
  • Critical path analysis and scheduling
  • Resource allocation over time
  • Milestone tracking and deadline management

Calendar View:

  • Date-based organization of work items
  • Deadline tracking and scheduling
  • Team availability and capacity planning
  • Integration with external calendar systems

Navigation Features

Search and Filter:

  • Full-text search across all node content
  • Advanced filtering by multiple criteria
  • Saved filter sets for common views
  • Quick access to recently viewed nodes

Minimap:

  • Bird's-eye view of entire graph structure
  • Navigation assistance for large graphs
  • Zoom indicators and position reference
  • Click-to-navigate functionality

Advanced Features

Graph Templates

Creating Templates:

  1. Design effective graph structure
  2. Document node types and relationships
  3. Save as template for reuse
  4. Share with team or organization

Template Categories:

  • Project Templates: Common project structures
  • Process Templates: Workflow patterns
  • Team Templates: Role-based organizations
  • Industry Templates: Domain-specific patterns

Integration Capabilities

Data Import/Export:

  • CSV import for bulk node creation
  • GraphQL API for custom integrations
  • Webhook notifications for external systems
  • REST endpoints for simple operations

External Tool Integration:

  • GitHub Issues synchronization
  • Jira import and bidirectional sync
  • Slack notifications and commands
  • Calendar integration for deadlines

Analytics and Insights

Graph Analytics:

  • Network analysis metrics (centrality, clustering)
  • Flow analysis for bottleneck identification
  • Velocity tracking and trend analysis
  • Team performance insights

Reporting Features:

  • Custom reports with visualization
  • Scheduled reports via email
  • Dashboard creation for stakeholders
  • Export capabilities for presentations

Best Practices

Graph Design Principles

Start Simple:

  • Begin with core outcomes and major milestones
  • Add detail incrementally as understanding develops
  • Avoid over-engineering initial graph structure

Clear Relationships:

  • Use specific edge types rather than generic connections
  • Document relationship rationale in descriptions
  • Validate dependencies don't create impossible cycles

Meaningful Priorities:

  • Set executive priorities for strategic alignment
  • Encourage individual priority expression
  • Let community validation drive resource allocation

Team Collaboration

Onboarding:

  • Graph orientation for new team members
  • Role clarification and permissions setup
  • Training on priority system and boosting
  • Practice sessions with non-critical graphs

Maintenance:

  • Regular graph hygiene - archive completed work
  • Priority reviews - adjust as strategy evolves
  • Relationship validation - verify dependencies remain valid
  • Performance monitoring - watch for bottlenecks

Scaling Considerations

Large Graphs:

  • Subgraph organization for complex projects
  • Filtering strategies for focused views
  • Performance optimization for smooth interaction
  • Access controls for information security

Multi-Team Coordination:

  • Cross-graph dependencies for program management
  • Federated graphs with clear boundaries
  • Coordination mechanisms for shared resources
  • Conflict resolution processes

Troubleshooting

Common Issues

Graph Performance:

  • Slow rendering - Reduce visible node count with filters
  • Memory usage - Close unused browser tabs
  • Network delays - Check connection to GraphQL API

Relationship Problems:

  • Circular dependencies - Use cycle detection tools
  • Broken connections - Validate target nodes exist
  • Permission errors - Check user access rights

Priority Issues:

  • Unexpected positioning - Review priority calculations
  • Boost not working - Verify anonymous rating enabled
  • Priority conflicts - Use community validation

Support Resources

Documentation:

  • API Reference - Complete GraphQL schema
  • User Guide - Step-by-step workflows
  • Video Tutorials - Visual learning resources
  • FAQ - Common questions and solutions

Community:

  • Discussion Forums - User community support
  • Feature Requests - Suggest improvements
  • Bug Reports - Report issues for resolution
  • Best Practices - Share successful patterns

The GraphDone graph creation workflow empowers teams to visualize, prioritize, and coordinate their work through natural dependency relationships rather than artificial hierarchies. The system scales from individual projects to organizational programs while maintaining democratic prioritization and collaborative decision-making.