Understanding .udoc Files: A Quick Guide
What is a .udoc?
A .udoc file is the native document format for the Ubik Research Environment. It is a structured, editable document container designed to support collaborative research workflows, including writing, citation management, evidence linking, and revision tracking. Unlike static formats (PDF, Word), .udoc files are dynamic: they integrate with the Ubik workspace, allowing you to cite notes, reference search results, and maintain version history throughout your research and writing process.
Think of a .udoc as a "smart document" that knows about your research. When you write in a .udoc, you can directly link to evidence in your workspace, making your citations live and traceable.
Creating Documents
To create a new .udoc file:
- Start a new document in your Ubik workspace by selecting "Create Document" or using the document creation menu.
- Name your document with a clear, descriptive title (e.g., "Literature Review: Machine Learning Ethics").
- Set the document mode: Choose between create (blank document for new writing) or edit (open an existing .udoc to modify).
- Define your structure: Add section headings and outline your main sections before writing detailed content.
- Begin writing: Use the built-in markdown editor to write paragraphs, add headers, and format text.
In practice, you use the ask_writing_agent_create tool, providing a title, writing request, target word count, and evidence notes. The system scaffolds the outline and fills content automatically.
Editing Documents
Editing a .udoc file is intuitive and supports multiple workflows:
- Direct text editing: Select text and edit in place using the markdown editor. Changes are saved automatically.
- Section management: Add, remove, or reorganize sections using the section structure panel. You can insert content at specific sections or append to the end.
- Citation insertion: Use the citation tools to link to notes, search results, or workspace evidence. Citations appear in the format
[noteId:page]or[sr:shortId:sessionShortId]. - Revision tracking: The .udoc system tracks all edits and versions, allowing you to review who changed what and when.
- Collaborative editing: Real-time collaborative editing is supported within the Ubik environment. The system handles synchronization automatically, though document edits are typically sequential (one user at a time for best experience).
Reading and Reviewing
To effectively read and review .udoc files:
- Navigate sections: Use the table of contents or section panel to jump to specific areas of the document.
- Follow citations: Click on citations (e.g.,
[noteId:page]) to view linked evidence directly from the workspace. - Review comments: Check for inline comments, suggestions, and flags left by collaborators during the editing process.
- Compare versions: Use the revision history to see how the document evolved and identify key changes.
- Export or finalize: When ready, finalize the document to lock it for review or export to other formats (PDF, Word) if needed.
When to Use .udoc
Use .udoc files in these scenarios:
- Research papers and essays: Write academic content with integrated citations to your research notes.
- Literature reviews: Synthesize evidence from multiple sources while maintaining live links to the original notes.
- Project proposals: Draft proposals with embedded evidence and collaborative feedback.
- Collaborative writing: Work with teammates on a shared document with built-in version control and commenting.
- Long-form research documents: Any document longer than a few pages that benefits from structured sections, citations, and revision history.
For example, our team uses .udoc for literature reviews synthesizing research papers, research briefs summarizing findings, and collaborative analysis documents where multiple team members contribute sections.
Key Benefits
.udoc files offer several advantages for researchers:
- Live citations: Direct links to workspace evidence make your sources traceable and verifiable.
- Integrated workflow: Write, cite, and review without switching between applications.
- Version control: Automatic tracking of edits and revisions ensures you never lose earlier versions.
- Collaboration: Multiple users can contribute, comment, and refine documents in real time.
- Structured organization: Built-in section management keeps long documents organized and navigable.
- Export flexibility: Finalize and export to standard formats when you need to share outside Ubik.