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

Document Naming Conventions

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.

Annotations

Placeholders

Syncing With Source Documentation

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

See

Create a link to a reference. <div class='ddd-container ddd-see'><span class='ddd-type'>see</span>: ... <div></div></div> Clone

Copy 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.