DITA Adoption TC Wiki
dita.xml.org Content Review
Existing dita.xml.org Content
A. Capabilities of DITA (JoAnn Hackos)
B. Setting up DITA (Keith Schengili-Roberts)
- Getting started - information good, but needs to be updated; most external links are dead
- Getting started as cheaply as possible - outdated; drop
- Resources for Beginners - many links to external resources that no longer exist; a good idea that needs updating
- Migrating legacy content - focus is on migrating content from Frame; rename and update(?)
- Installing the DITA Open Toolkit - outdated; update
- Setting up stylesheets and a publishing system - outdated; update
- Setting up the Eclipse Help Infocenter for publishing DITA content - outdated, drop
- About authoring tools - holds up; keep (but update)
- About storing and managing content - update
File and folder naming - doesn't really address issue well; drop/replace||
C. Working with DITA (Stan Doherty)
I wonder whether developing and maintaining original tutorial content makes sense, given the number of available books, YouTube videos, slide stacks, and whitepapers. Anyway ...
- Writing DITA topics (rewrite)
- Working with maps (rewrite)
- Working with images (rewrite)
- Working with content references - conref (rewrite, keys)
- Working with links (rewrite, keys)
- Working with conditional text (rewrite)
- Publishing with the DITA Open Toolkit (move)
- Optimizing DITA for Translations (move)
- Stem sentences (remove or move)
- Myths about technical writing (move)
- Developing reuse strategies (update)
- Math Domain (rewrite)
D. The DITA Open Toolkit (Keith Schengili-Roberts)
- The DITA Open Toolkit - updated semi-recently (2013); keep (update)
- Installing the DITA Open Toolkit - outdated; update
- Installing OT on the Mac - can't comment if this is still valid; likely outdated
- Publishing with the DITA Open Toolkit - updated semi-recently (2013); keep (update)
- Plugins for the DITA Open Toolkit - updated semi-recently (2013); keep (update)
- About Plugins - suggest this single-para piece just be added to revamped version of "Plugins for the DITA Open Toolkit"
- Plans for future versions of the DITA Open Toolkit - outdated; drop
- Plans for the DITA Open Toolkit PDF2 Plug-in - outdated; drop
E. DITA Community (Keith Schengili-Roberts)
- List of organizations using DITA - useful but needs updating (several firms listed no longer exist); link to DITAWriter?
Comments (Mark Poston): Having a list of organizations is very useful. I was thinking that we might invite community members who belong to these organisations to contribute an article that describes their organization’s use of DITA. This might be an article within the site or an external resource. For example, there may be case study presentations at a conference that can be linked to. One of our proposed features of the new site was be to link to external resources and embed them, such as slideshare, YouTube etc. The list then becomes a much more valuable resource to visitors of the site and avoids losing visitors to another site.
Examples of documents created in DITA - only avail to logged in users (why?); ought to link instead to samples on GitHub
- List of speakers for DITA presentations - only two speakers listed, not a critical resource; drop
- DITA user groups - mostly links to internal pages most of which date to late 2000s; update(?)
- DITA Conferences - outdated (2008); update
Comments (Mark Poston): There will be support for “events” within the new site. This will allow users to upload information about an upcoming event. It would also allow other users to create related articles about an event. This might be a review article about the event. It might be a link to a resource about the event … perhaps a presentation. This then becomes a useful resource for new and old events. If visitors know they can go to an old event (say DITA Europe 2012) and find useful information about it, even if they are to external resources, it turns DITA.xml.org into a much more useful site than it currently is - and, hopefully, keeps people coming back.
- Blogroll - update (do we keep ones that still exist but haven't updated since late 2000s?)
- Testimonials for DITA 1.2 Implementation - consists of a single recommendation; drop
- HAWEBS.NET - DITA Community (Simplified Chinese) - dead link; drop
F. The Business Case for DITA (Keith Schengili-Roberts)
Essentially all but the first article are disposal/out-of-date. The focus of most of the questions just seems just seems odd 7 years after these were all written. Many of the articles are too brief or too much off topic to be directly useful attempting to use them today. Suggest a re-write of the main article and dispose of the rest.
Note: several articles link to ditausers.org which is effectively dead
- Making the Business Case for DITA - REWRITE (decent content, but many links to ditausers.org which are design to underscore key points)
- Is content management important? - REMOVE (good subject, sole focus is on WCMSes, *long* out of date)
- Is structure important? - REMOVE (focus almost solely on history of IA, not on business case for why structured content is worthwhile)
- Is content reuse important? - REMOVE (subject good, outdated)
- Is single-sourcing important? - REWRITE (could do with a re-focus/update, but is still accurate)
- Is translation important? - REMOVE (subject good, content outdated and too brief to be useful)
- Do you markup your content? - REMOVE (outdated)
- Is your content modular? - REMOVE (wrong question to ask, outdated)
- Is your content conditional? - REMOVE (wrong question to ask, outdated)
- Is your content task-oriented and minimalist? - REMOVE (wrong question to ask, outdated)
- Is standardization important? - REMOVE (outdated)
- What is your DITA Quotient (D.Q.)? - REWRITE (laughably outdated but a good idea; relies on links to DITANew.com which is also dead)
G. The DITA Maturity Model (M. Priestly/A. Swope)
Comment (Amber): Michael and I mentioned this the last time we saw each other, but I don’t know that we made a decision about it. The information is still valid, but there may be additional information that we could provide to augment or illustrate each of the levels.
H. DITA Specializations Development (Bob Thomas)
These articles are quite dated. The first two titles remain relevant; unfortunately, their content does not.
- Introduction to specialization: Rewrite
- Guidelines for Specializers: Rewrite
- Troubleshooting specialization: Remove
- Training specialization: Remove
- OASIS DITA specialization subcommittees: Remove
I. DITA Standards Development (Keith Schengili-Roberts)
- In general all of the material in this section is outdated, but some pieces should be kept for archival purposes and others updated for DITA 1.3
New Content (Authored or Referenced)
Jacquie Samuels suggested that we consider some of the following articles:
- Keywords: why, where and when to use them by Amber Swope
- Reuse strategies and the mechanisms that support them by France Baril
Do We Really Need All that Glue? by JoAnn Hackos, PhD
- Specialize, but not right away by Bruce Esrig
Probably really out of date: http://dita.xml.org/resource/dita-metada-and-taxonomy: KrisEberlein
- Specialization guide by Eliot Kimber (Mark Poston had previous permissions to use and will double check)
- DITA Style Guide by Tony Self (Mark Poston has alreayd obtained permission from Tony to use in DITA.xml.org)
...