---
title: 'DDD Issues'
url: 'https://www.twelvetone.tv/docs/developer-tools/document-driven-design/ddd-issues'
markdown: 'https://www.twelvetone.tv/docs/developer-tools/document-driven-design/ddd-issues.md'
date: '2026-09-25'
description: 'Developing documentation has issues. These issues are different, albeit comparable, to issues the developers will face. This d'
taxonomy:
  category:
    - docs
  devtype:
    - private
---

[](#)  [ Home ](https://www.twelvetone.tv/docs/)     [ Developer Tools ](https://www.twelvetone.tv/docs/developer-tools)     [ Document Driven Design (DDD) ](https://www.twelvetone.tv/docs/developer-tools/document-driven-design)      DDD Issues    

# DDD Issues

Developing documentation has issues. These issues are different, albeit comparable, to issues the developers will face.

This document poses questions and offers solutions to common scenarios.

## Structure

### Organizing files

1 file? Multiple files? Folders? Indexes?

### Organizing Content

### UI

#### Fields

#### Preferences

#### Actions

### Hierarchy

How should the information be structured? By feature/doc-type or doc-type feature. Perhaps favor the writer over the reader, so feature/doc-type would be best.

## Conventions

A consistant way to name things.

### Naming Conventions

todo: 

### Document Naming Conventions

todo: 

### Tense

The documentation should be in a consistent tense. Use the imperative, present tense: "change", not "changed" or "changes".

## Issue Management

Collecting, categorizing, prioritizing, assigning, and viewing issues.

see: Issue Management

## Annotations

see: Annotations

## Placeholders

todo: 

## Syncing With Source Documentation

todo: 

## Versioning

What features and fixes made it into what releases.

## Coverage

How much God has been documented?

## Keeping UI changes in sync

## Links

Links create connections between sections and document and document types.

## Source Code Documentation

How to link to source code documentation? The *javadoc* directive will merge or link in the indicated package or class documentation.

```
<div class='ddd-container ddd-javadoc'><span class='ddd-type'>javadoc</span>: package com.foo.bar<div></div></div>
<div class='ddd-container ddd-javadoc'><span class='ddd-type'>javadoc</span>: class com.foo.bar.TheClass<div></div></div>
```

### Annotations

SeeCreate a link to a reference. ` <div class='ddd-container ddd-see'><span class='ddd-type'>see</span>: ... <div></div></div> `CloneCopy information from another section. ` <div class='ddd-container ddd-clone'><span class='ddd-type'>clone</span>: ...<div></div></div> `\### Template Common descriptions can be duplicated or linked to. Template Definitions ` [tab press <tab> to move between fields] `U-Doc ` Save Document Form `` [tab] `\## Collaborative Editing How to handle multple editors at the same time. How to merge changes.  

 [ ](https://www.twelvetone.tv/docs/developer-tools/document-driven-design/ddd-example-workflow) [](https://www.twelvetone.tv/docs/developer-tools/relaxed-json)

---

## Navigation

- Parent: [Document Driven Design (DDD)](https://www.twelvetone.tv/docs/developer-tools/document-driven-design.md)
- Previous: [Example Workflow](https://www.twelvetone.tv/docs/developer-tools/document-driven-design/ddd-example-workflow.md)