DITA design

SandraBowman
Posts: 1

DITA design

Sat Sep 23, 2017 12:54 pm

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: 5088

Re: DITA design

Mon Sep 25, 2017 9:26 am

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: 5088

Re: DITA design

Wed Sep 27, 2017 7:57 am

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/162465-6317143154172706819?midToken=AQEJ9lSAre4ccQ&trk=eml-b2_anet_digest_of_digests-hero-11-discussion%7Esubject&trkEmail=eml-b2_anet_digest_of_digests-hero-11-discussion%7Esubject-null-la7zl%7Ej81fcmkx%7Eaq-null-communities%7Egroup%7Ediscussion&lipi=urn%3Ali%3Apage%3Aemail_b2_anet_digest_of_digests%3BOhBWFwjARIO6Nkd5cBbSSg%3D%3D

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Return to “DITA (Editing and Publishing DITA Content)”

Who is online

Users browsing this forum: No registered users and 1 guest