DITA design

Post here questions and problems related to editing and publishing DITA content.
SandraBowman
Posts: 4
Joined: Fri Sep 08, 2017 2:49 pm

DITA design

Post by SandraBowman »

Hi, quick question.

Which of the following approaches do you find preferable?

1. Keeping reference material close to the task it relates to in a concept > tasks 1-3 > reference > concept > tasks 4-8 > reference sort of structure.

2. Splitting out the concepts, tasks and reference material in an all concepts > all tasks > all reference sort of structure.

The first can mean the tasks feel cluttered with too much information around them.
The second can mean that someone who wants the detail up front is irritated by having to link to a reference topic later in the document.

So, which approach do your users prefer? Would appreciate any views!

Many thanks :)
Radu
Posts: 9018
Joined: Fri Jul 09, 2004 5:18 pm

Re: DITA design

Post by Radu »

Hi Sandra,

I think this would be a question that you could also register and ask on the DITA Users List, the Oxygen forum is a more static place, usually only we the Oxygen devs are notified when a new post is made.

Initially I think most people preferred to have 3-4 folders named "tasks", "concepts", "topics", "references" at the root of the project and save each newly created DITA resource in one of those.
But I think that recently people are more inclined to split the DITA resources into folders by semantic meaning and not by topic type.
For example Oxygen XML Editor has an XSLT Debugger and a Database perspective. Maybe for the Oxygen User's Manual I would create a "debugger" folder in which I could add all the XSLT debugger-related DITA resources (no matter of what topic type they belong to). And I could also create a "database" folder with the database-related DITA resources + maybe an "images" folder with the database-related images. Also while I'm there in the "debugger" folder I could create a DITA Map which references the debugger topics and is in its turn referenced in the larger main DITA Map which would reside in the project root folder.
So I would recommend to stop splitting DITA resources into folders by topic type and instead create folders for various components in your larger project.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
Radu
Posts: 9018
Joined: Fri Jul 09, 2004 5:18 pm

Re: DITA design

Post by Radu »

Hi Sandra,

I see that you also posted on LinkedIn and I now see that I did not properly understand your original question, I thought that you actually meant in what folder hierarchy to store topics/concepts and tasks.

Anyway, for completion I'm linking here to the useful answers you got on LinkedIn:

https://www.linkedin.com/groups/162465/ ... bSSg%3D%3D

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
SandraBowman
Posts: 4
Joined: Fri Sep 08, 2017 2:49 pm

Re: DITA design

Post by SandraBowman »

Hi Radu,
A belated thank you for your very helpful reply which I have only now spotted. :oops:
Thank you!
Radu
Posts: 9018
Joined: Fri Jul 09, 2004 5:18 pm

Re: DITA design

Post by Radu »

Hi Sandra,

No problem, whenever you post you can check some checkboxes to be notified via email when a thread is updated.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
SandraBowman
Posts: 4
Joined: Fri Sep 08, 2017 2:49 pm

Re: DITA design

Post by SandraBowman »

OK, thank you and thanks also for suggesting the DITA Users group.
Sandra
Post Reply