Best practices

Posts: 1
Joined: Fri May 24, 2019 12:32 am

Best practices

Post by al-UK » Fri May 24, 2019 1:05 am

My company recently hired some 'highly-experienced' DITA writers to assist in the implementation of a content reuse system.
Problem being that one has never seen DITA in text view (with the angled brackets) and the other didn't know how to make a table - so I have serious concerns about their competency.

Prior to hiring these workers we had an external company come in to help us define a new DITA information model.

Both the new workers and the external company have defined best practices for us but these are conflicting. DITA is new to me so I thought asking here would help resolve some issues.
  • Constraint of elements: The external company thought we should minimise our model; removing elements that we would rarely or never use to make it easier for both our writers and stylesheet developer. The new workers we have want to be able to use almost everything that is available.
  • Use of bold, italic and underline: The external company believe we should only keep one of these. Using it only where it would not make sense to use a more descriptive term; cite, term, etc. Again the new workers want to be able to use everything.
  • Use of tables in non-reference topics: One of our workers believes it is best practice not to use tables in non-reference topics. We should instead put our tables into reference topics and then link the non-reference topics to the tables in the reference topics using reltables . This is not something that has been discussed with the external company, but to me it seemed like a complicated way of handling information. I could understand if we had huge tables that took up many pages. But usually our tables are very small only having a few columns and rows

Posts: 6503
Joined: Fri Jul 09, 2004 5:18 pm

Re: Best practices

Post by Radu » Fri May 24, 2019 9:16 am


I agree for the first two rules with the external company. About prohibiting tables usage inside topics, I have not heard anybody else prohibit the use of tables inside topics.
Ideally you should also register and ask around on the DITA Users List (Yahoo Group), we have plenty of DITA users registered on the Oxygen forum but most of them are not notified automatically when new posts are added.

Radu Coravu
<oXygen/> XML Editor

Post Reply