Problems finding the right architecture
hi there,
i'm trying to convince our developers and intermediate management to focus on DITA in our next software generation, a web-based application for government administration. the difficulty is: i'm left alone on that task and have no help whatsoever since documentation is seen as very unimportant (but everybody will be complaining in the end when there's no documentation).
i understand that topic-based documentation and single source does not necessarliy mean that you *have* to use XML or DITA. i'd like to use DITA but maybe it won't work out this way. however, i'd like to use a topic-approach, even if our management decides not to use DITA or XML at all.
i hope i got it right: developing a topic-based documentation is all about getting information cut into small bits that stand on their own and then "tieing" it together with a map. this is technology-neutral and could be done in word, if someone likes. right? ;-)
i'm trying to achieve that but have serious difficulties in finding the right "entry point" for creating the right "information architecture". as stated above: i'm alone on the documentation issue and no-one has the courage to help me and i have very sparse information about the software that has to be documented.
i've also read the whitepapers "planning for dita success 1/2" but i just don't get it right.
now my questions: i've created a set of topic-classes but i'm unsure if they fit and/or how to continue. is it a good idea to try the structure within a small area of the software? does the information architecture "evolve" from there on or must it be well-designed from the beginning? i attached some of my topic-classes - am i doing it right (i translated the topic-classes to english, the rest is german)?
thanks a lot in advance!
tk
| Attachment | Size |
|---|---|
| classes.pdf | 56.56 KB |
Search
Recent Content
- Forum for DITA Users
35 weeks ago - Publishing for DITA
5 years ago - Optimizing the DITA Authoring Experience — Online Course
5 years ago - Linking to another chunked topic
5 years ago - Advanced Reuse Strategies — Online Course
5 years ago - 2019 Content Management Strategies/DITA North America Conference
5 years ago
Subscribe
been there
Hi tkhis -
Sounds like your situation is similar to one I was in a few years ago. The main piece you are going to need to succeed with topics and single sourcing is the cms; in particular, you will need a component content management (CCM) to handle xml objects and their attributes and relationships.
It sounds as if you are a solo contributor or on a small team. You don't mention what tools you are using at the moment, but when I was in a similar situation, I made a decision to go with a relatively low-cost application that integrated the ccm, the authoring front end, and the publishing transforms so that I could focus on writing instead of trying to roll my own solution. This was before the application I chose added support for DITA, but I was able to set up a very DITA-like environment even then, so I'll assume that if you went the same route as me you could implement DITA in your own time frame.
My advice - it sounds like you have a lot of plates in the air and not a lot of support - use DITA if and when you can, but don't go into the tools development business as a solo act.
Hope that helps, and good luck!
hi, currently, we are
hi,
currently, we are using mediawiki as a "scrapbook" for documentation. it is a collection of use-cases, notes et cetera. the current opinion of our delevopers on this issue: "what do you want? this *is* the documentation, now go away, we have no time." :-/
you mentioned "low-cost" solutions that integrate a ccm - which one?
thanks in advance
tk
structuring documentation
Here's a quick reply with a few suggestions.
Have you done a content analysis? You need to know what audiences, duties, and tasks you need to cover.
It looks as though you've thought about the page layouts of the items you need to explain, and based your types upon that. But the types should be based on what structures you need to use rather than being based on what content you need to describe. You might be able to use a single topic type for multiple content types ... describing a frameset and a fieldset could require the same DITA elements ... they would differ in what links you support to and from them.
If your "task" is not sequential, then it could be a concept type. The real task type is "flow". There has been a trend away from extensive summaries, so you might want to put your goal statement first. Any summary information that you want to provide might be in a separate concept topic.
To get people interested, the best you can do is come up with a content outline and a development schedule. When people see the lead time required to do all the content development, they may start to work with you earlier in the schedule.
Yes, doing a pilot on a small portion of the content is a good approach. Any samples that you can show will help to make your case more vivid. And you will surely learn about some things you would otherwise have overlooked.
Bruce Esrig Information Architecthi, thank you for your kind
hi,
thank you for your kind answer. have i done content analysis? not really. what i'm trying to do is "content guessing" because there is no way for me to do proper content analysis since no one of the developers or "decision-makers" has the time to cooperate with me on this manner. this is an in-house problem i somehow must solve... :-(
however i have another question concerning dita:
our software is extremely configurable. we ship it with a set of pre-installed "reference models". choosing one of those reference models leads to changes within the application: on workflow-level (a whole workflow might differ between the chosen reference models), on task-level (e.g. based on the reference model, the same task has 4 instead of 5 options) and on the gui-level (based on the reference model, a workflow might be the same but requires different actions with the gui).
my take is to use the generic dita-classes concept, task and reference and evolve from there, but how do i cope with this high level of customizability?
for example: there are topics "doing A" and "doing b" (tasks) in reference model 1. "doing A" concists of, let's say, 10 steps, "doing B" concists of 3 steps.
now there is reference model 2. it is nearly the same, but concists of "doing A", "doing B" and "doing C", where "doing A" is one step shorter and "doing B" one step longer.
even more complex: our system is highly integrated. for example, it comes with a build-in mail-system that is used in different locations of our software, lets say in "area 1" and "area 2". so it makes perfectly sense to describe the usage of this mail-system once and just link or embed this topic where it is needed.
however, choosing one reference model might lead to the following situation: the same mail-system does look a bit different in "area 1" than in "area 2", e.g. maybe one element is missing.
my question: how do i re-use content under such circumstances, where the "smallest" type of information (a single task, a single concept or a single reference) does not seem to be "small" enough?
Conditional processing and conref
Sorry this didn't get answered before - but in case others have the same question, you can customize content within a topic using conditional processing to flag elements for inclusion/exclusion, and conref to reuse common elements.
So you could have a single task - "doing X" - that documents the superset of steps for doing A/B/C and then you exclude the steps you don't need when producing a specific task.
Michael Priestley