> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vistaly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Drafting Documents

> Step-by-step guide to generating AI-powered documentation

<Info>
  **Beta Feature:** AI Document Drafting is currently in beta. We're actively improving the feature based on user feedback.
</Info>

# Drafting Documents

This guide walks through the complete workflow for generating AI-powered documentation, from template selection to final draft.

## Starting a Draft

AI drafting is available in three locations throughout Vistaly.

### 1. Card Description Editor

The most common entry point for creating card documentation.

**Steps**:

1. Open any card in your workspace
2. Look for the **"Draft with AI Templates"** button in the description field
3. Click to launch the drafting workflow

**When to use**:

* Documenting opportunities, solutions, or problems
* Creating comprehensive card descriptions
* Generating structured documentation from workspace data

### 2. Jira Integration

Generate issue descriptions when creating Jira issues from Vistaly.

**Steps**:

1. Create a Jira issue from a Vistaly card
2. In the issue creation dialog, click **"Draft with AI Templates"** in the description field
3. Select a template and generate

**When to use**:

* Creating detailed Jira issues from Vistaly cards
* Ensuring Jira tickets have comprehensive context
* Maintaining consistency between Vistaly and Jira

### 3. Linear Integration

Generate issue descriptions when creating Linear issues from Vistaly.

**Steps**:

1. Create a Linear issue from a Vistaly card
2. In the issue creation dialog, click **"Draft with AI Templates"** in the description field
3. Select a template and generate

**When to use**:

* Creating detailed Linear issues from Vistaly cards
* Ensuring Linear tickets have comprehensive context
* Maintaining consistency between Vistaly and Linear

## Step-by-Step Workflow

The AI drafting workflow consists of several distinct steps:

### Step 1: Template Selection

After clicking "Draft with AI Templates", you'll see all published templates compatible with your current card type.

**What You'll See**:

* Template name and icon
* Brief description
* Preview of template sections (expandable)

<Tip>
  Hover over any template to expand and preview its sections before selecting if you're unsure which one you should use.
</Tip>

### Step 2: Context Collection

After selecting a template, you'll provide additional context. By default, Vistaly's document drafting experience will only generate content when evidence exists to support it. This is your opportunity to share any context you have to improve the quality of the output with infrormation not stored in Vistaly.

#### What is Extra Context?

Extra context is **optional** information that's not captured in your Vistaly workspace.

**What AI Already Knows**:

* Your target card plus relevant surrounding context
* All comments on these cards
* All customer insights linked to these cards
* Your organization description (from Settings)

You don't need to repeat any of this information.

**When to Provide Extra Context**:

✅ **Do Provide**:

* Specific technical requirements from external docs
* Stakeholder decisions made in offline meetings
* Research or data from other tools
* Context from outside your workspace
* Any context required by your template that lives outside of Vistaly

❌ **Don't Provide**:

* Information already in your card hierarchy
* Insights already linked to cards
* General requests like "make it detailed"
* AI instructions (use template sections for this)

**Example Extra Context**:

```markdown theme={null}
## Additional Requirements
- Must integrate with Salesforce API
- Target launch: Q2 2024
- Engineering budget: 3 developers for 6 weeks

## Stakeholder Input
From 1/15 planning meeting:
- VP Sales wants mobile-first experience
- Support team needs admin dashboard
- Compliance requires audit logging
```

#### Navigation

* **Back to Templates**: Return to template selection
* **Generate Draft**: Proceed with AI generation (disables after clicking)

### Step 3: Generation

After clicking "Generate Draft", AI processes your request.

**What Happens** (10-30 seconds):

1. **Data Collection** (automatic):
   * Fetches target card and additional context
   * Retrieves all linked customer insights
   * Retrieves all comments on these cards
   * Fetches your organization description

2. **AI Processing**:
   * Combines workspace data with template structure
   * Integrates your extra context
   * Links all required insights to source cards
   * Acknowledges gaps where evidence is missing
   * Generates structured markdown

3. **Display**:
   * Editor opens with generated content
   * Content is fully editable

### Step 4: Reviewing the Draft

The generated draft appears in a markdown editor, ready for review and editing.

**What You'll See**:

**Structured Sections**:
Every section from your template, populated with relevant content:

```markdown theme={null}
## Customer Evidence

Based on customer feedback, teams need better collaboration
([Company A](link1), [Company B](link2)). Users specifically
mentioned challenges with real-time updates ([Company C](link3)).

> "We waste hours each day syncing across tools."
> — Jane Smith, [Company A Interview](link1)
```

**Linked Insights**:
All required insights are linked as clickable references back to source cards in Vistaly.

**Evidence-Based Content**:
Only information from your workspace is included. No fabrication.

**Acknowledged Gaps**:
When evidence is missing, AI explicitly notes it:

```markdown theme={null}
## Market Sizing

*(Evidence not yet available)*
```

This is intentional and better than fabricated information.

```markdown theme={null}
## Additional References

- Workflow friction challenges [[1]](url1)[[2]](url2)
- [Users struggle to find insights](url3) (Company X)
```

### Step 6: Saving Your Draft

Once you're satisfied with the content:

1. Click **Save** or use your platform's save mechanism
2. The draft becomes your card description (or Jira/Linear issue description)
3. All insight links are preserved and clickable

## Preparing for Better Drafts

The quality of your generated drafts depends on the data in your workspace.

### Before Drafting

**Link Relevant Insights** to your card and surrounding context:

* AI pulls insights from target card and related cards
* More insights = richer, more evidence-backed content
* Insights closer to your target card are prioritized

**Update Organization Description** (Settings > Advanced):

Set your organization description to help AI understand your business context. Include:

* Your industry and market
* Product focus and offerings
* Target customers
* Company mission or value proposition

**Example**:

> "Acme Inc. is a B2B SaaS company building project management software for distributed engineering teams. We focus on mid-market companies (50-500 employees) in the technology sector. Our platform combines real-time collaboration with automated workflow management to help remote teams coordinate complex software projects."

**Choose the Right Template** for your use case:

* Early exploration: "Opportunity Summary"
* Building solution: "Solution Brief"
* Specialized needs: Custom template

## Workflow Tips

### First Draft Mindset

Treat generated drafts as a strong starting point, not a final product:

* **Review for accuracy**: Verify all linked insights are relevant
* **Fill gaps**: Add missing information manually
* **Enhance**: Expand sections that need more detail
* **Refine**: Polish tone and structure

### Iterative Refinement

For complex documents:

1. **Generate initial draft** with template
2. **Manually review and edit** for accuracy and completeness

### Time Savings

* **First draft**: Seconds (AI generation)
* **Review and edit**: Minutes to hours (depending on complexity)
* **Total time**: 50-80% faster than starting from scratch

Focus your time on strategic thinking and refinement rather than structure and evidence gathering.

## Workflow Approaches

Different approaches work for different documentation needs:

### Quick Draft Approach

For routine documentation or early-stage exploration:

1. **Generate with template** (1-2 min)
2. **Quick manual edit** (5-10 min)
3. **Save and iterate later**

**When to Use**: Internal docs, early drafts, rapid prototyping

### Three-Pass Approach

For complex, important documents:

**Pass 1 - Generate Structure** (AI):

1. Select template and generate initial draft
2. Review for completeness and structure
3. Identify gaps and missing evidence

**Pass 2 - Fill Gaps** (Manual):

1. Add missing information from other sources
2. Link additional insights
3. Enhance thin sections
4. Correct any inaccuracies

**Pass 3 - Final Polish** (Manual):

1. Polish tone and readability
2. Final review for accuracy

**Time Investment**: 30-70 minutes vs. 2-4 hours from scratch

### Progressive Refinement Approach

For documents you'll build over time:

1. **Generate skeleton** early with limited data
2. **Review and identify gaps**
3. **Add evidence** (insights, comments) to workspace
4. **Regenerate** as you gather more information

**When to Use**: Long-running initiatives, evolving documents, research-heavy projects

## Troubleshooting

### Template Not Available

**Checklist**:

* Is the template published? (Check Settings > Templates)
* Does the template support your card type?
* Refresh the page to load latest templates

### Missing Expected Insights

**Possible Causes**:

* Insights aren't linked to card or surrounding context
* Insights are too far removed from the target card
* Template sections don't align with insight content

**Solutions**:

* Link insights directly to target card or closely related cards
* Ensure insights are connected to relevant cards in your hierarchy
* Adjust template section descriptions to match available data

### Draft Quality Issues

**Sparse Output**:

When your draft feels thin, try these solutions:

* **Link more insights** from customer interviews or research to the card and surrounding context
* **Add comments** to cards with key context before drafting (stakeholder feedback, decisions, requirements)
* **Use extra context field** generously for information not in Vistaly (meeting notes, research, requirements)
* **Accept shorter draft with gaps** and fill manually as needed

**Missing Metrics or Data**:

When template asks for metrics but you don't have them yet:

* **Accept the gap** - AI will note `*(Evidence not yet available)*` which is honest and appropriate
* **Define metrics separately** in a working session
* **Manually add to draft** once defined
* This honest documentation evolves as you gather data

**Generic Output**:

When draft feels vague despite having data:

**Likely Causes**:

* Template section descriptions too vague
* Template too broad for use case
* Missing organization description
* Insufficient extra context

**Solutions**:

* Improve template section descriptions with specific guidance
* Create more focused templates for specific card types
* Add organization description in Settings > Advanced
* Provide targeted extra context for specific requirements

**Duplicate Information**:

If same insight appears multiple times:

* Link insight to **most relevant card only** in your hierarchy
* AI prioritizes insights from closer cards, so linking to the most specific card prevents redundancy

**Missing Sections**:

* Check template has complete sections (both title and description)
* Verify template is published
* Try regenerating

### Generation Takes Too Long

**Normal**: 10-30 seconds depending on data volume

**Too Long** (>60 seconds):

* Check internet connection
* Try refreshing and regenerating
* Contact support if persistent

## Best Practices

### Before Drafting

* [ ] Review card hierarchy and linked insights to get a sense of what's available
* [ ] Choose appropriate template for use case
* [ ] Prepare extra context if needed

### During Review

* [ ] Check for acknowledged gaps and determine if acceptable
* [ ] Assess overall structure and flow
* [ ] Note sections that need expansion

### After Drafting

* [ ] Fill acknowledged gaps with manual content
* [ ] Enhance sections with additional context
* [ ] Polish tone and readability
* [ ] Save and share with team

## Next Steps

* **[Template Management](/documentation/ai-document-drafting/template-management)**: Create custom templates for your needs

***

Questions about the drafting workflow? Contact us at [support@vistaly.com](mailto:support@vistaly.com)