What steps should I follow to architect and write a large DITA document?
Author: Anna van Raaphorst
I followed the following general process to architect and edit DITA Open Toolkit User Guide and Reference (a document of over 300 topics and approximately 220 pages when built to PDF). The official writing team was only two people, but we got input from a number of other sources.
- Do a high-level design of the document with the key topics (in this case, "chapters," because it's based on the bookmap specialization).
- Do an assessment of any existing content and establish a migration plan.
- Create an appropriate directory structure.
- Create a top-level ditamap (and lower-level maps, if required).
- Add sample section/topic names to the chapters. Establish preliminary guidelines for file names and IDs.
- Decide on the metadata that will be included in each topic.
- Decide on the graphics guidelines.
- Establish a preliminary plan for linking the content.
- Establish a preliminary plan for content reuse (conref'ing).
- Set up the infrastructure and establish the procedures necessary for your team members to process both their own sections and the entire document.
- Review your progress and preliminary decisions with your other team members. Make adjustments, if necessary.
- Write sample topics and stub topics (all with metadata). Ask some of your team members to do this, as well.
- Make additional adjustments, as appropriate. Keep your name on the list of writers, if only for a small section.
- Assign topics to writers and ask them to write several additional sample topics. Meet with your team and make adjustments based on their feedback.
- Establish key files as templates or samples. Better yet (if you have time), write a style guide with lots of examples.
- Begin to edit some of your team's topics.
- After about 10-15% of the topics are in draft format, meet with your team to establish indexing guidelines. Adjust the guidelines up to about the 30% complete level, and then write up the indexing guidelines and stick to them.
- Continue to edit your team's topics.
- As information architect (or editor), process the entire document often, and look for problems. Meet with your writing team to establish an action plan for every issue. Reverse roles some of the time (writers edit, and editors write).
- When your team has approximately 40% of the content written, meet to establish the final guidelines for linking (both topic-to-topic and external, if relevant).
- Do regular TOC, indexing, and linking reviews.
- Establish criteria for the alpha and beta versions of the document.
- Meet with your team to review the publishing plan, including testing assignments.
- Create the alpha version of the document, test, and fix bugs.
- Create the beta version of the document, test, and fix bugs.
- Publish and distribute.