Documentation
I've been going through the DITA2Go documentation to get a sense of how to override presentation for specific elements. I think that the documentation needs streamlining because it's pretty difficult to determine how to do this task from what you currently have.
One of the problems is that there too many topics. The level of granularity in the document is too small, winding up with topics that are nothing more than a list of the topics in the section which just adds to the frustration. Some topics are so small that they really don't help because they really don't stand on their own. I think that the problem is one of trying to reuse existing topics from other sources and not focusing on DITA2Go as a unique product. The lack of focus makes the entire documentation suffer.
Suggestions for improvement:
- Consolidate the information better. You probably need to restructure and redesign the whole thing to achieve the best result.
- Make the tasks the focus and not the concepts. There's so much understanding material (and understanding isn't a task) and not enough focus on doing something. If I need to change the output for an element I should see a topic with a title like "Changing the output appearance of an element".
- Add examples. I'm not done going through the information yet but it's not obvious whether there are examples of how to do things that are easily findable. Consider examples of specific configurations as appendices (or a reference section) rather than scatter that information throughout topics. Duplication is not criminal, in this case, you can always just reuse the examples from one section to another.
- Simplify the explanation of the template override mechanism. I'm still unclear as to how this works. I think I need to specify a pointer to my override template and within that template make a reference to a base template to avoid breaking the output appearance but I wonder why I should even have to do that. I would expect the system to look at my template and just use what's there and when it encounters something not in my template to look towards the base templates to supply the definition. Having the user remember to point to the base templates is a recipe for failure.
Hope this helps.
Template overrides
Simplify the explanation of the template override mechanism.
We're currently finishing up another revision that does much of that for you. Basically, the new package, which will be up in a few days, adds a set of empty template files where you can put your changes, and only your changes, so they are not buried among the standard settings we provide as a starting point. That means that you don't have to add any of the links you don't like (which are essential), because they are already there.
The next revision includes a Project Manager utility that collects info from you and sets up new projects, modifies existing ones, and runs the resulting process with a single click. We've done this without compromising the ability to run from the command line, so you can also easily configure your favorite XML editor to run your projects. I often use oXygenXML for that.
We also have a template editor under construction that will provide even more detailed guidance about relevant settings, and make the edits in the correct .ini files for you. Personally, I prefer the flexibility of a text editor to a GUI, but we realize some folks find editing a structured file like an .ini challenging. (It's not a tenth as challenging as editing XSLT, but still.)
We'll email everyone in the Beta when the new package is ready, hopefully next week.
Documentation issues
Thank you for your thoughtful comments. A few general points, then I'll break out others into their own threads.
I think that the problem is one of trying to reuse existing topics from other sources and not focusing on DITA2Go as a unique product.
Interesting. Yes, just as DITA2Go is largely based on Mif2Go, the User's Guide incorporates a great deal of the Mif2Go docs. It would simply not be possible to have a 700-page doc (which is larger than Frame's docs) for the Beta release otherwise. But... one of the big advantages of DITA is that it encourages such re-use. About 30% is new, basically all of Chapters 1 through 10. And we have been very careful to edit the re-used parts, via both variables and conditional text, to keep only those points relevant to DITA.
The level of granularity in the document is too small, winding up with topics that are nothing more than a list of the topics in the section.
Document conversion is not a simple task. There are many ways writers approach it. While explaining "how to override presentation for specific elements" sounds simple, it's not. First of all, what sort of element? Very different processes apply to graphics, tables, related links, cross-references, text... there is no way to make one process fit all and still provide the flexibility that technical authors require. Then, consider the dozen possible output formats. You can't do the same things in Word RTF that you can in OmniHelp. So we have at least two major dimensions here, and in fact Chapters 11 through 32 deal with the format-specific issues. Then Chapters 33 through 38 address cross-format issues, and 39 through 43 deal with the automation process, a world of its own.
When you have a multidimensional problem, whichever way you come at it, you are going to have branching. If we were to duplicate content instead of using cross-references so heavily (the only other option), the User's Guide would be a lot more than 700 pages and way harder to maintain. AFAIK, we never actually have a leaf node that consists solely of xrefs, but if that were what was needed to get you to the precise info you need, we'd do it.
Another way of getting to the exact spot in very few steps is to use the index. We've put a lot of work into it, with over 1000 entries. and lots of see/see also references. That's what I tend to use first myself when answering support posts.