Add Tutorials section

[infotexture]

The OT docs should be extended with a dedicated Tutorials section that guides the reader through common use cases for new toolkit users, such as:

• Building output with the dita command
• Running dita builds with scripts
• Creating an Ant build script
• Customizing PDF output
• Adding custom branding to HTML output
• Publishing draft output with comments
• Highlighting revised content
• Creating plugins to override stylesheets & document type shells
• Best practices for plugin development

Several similar topics are currently available elsewhere in the docs (checked in the list above), but a dedicated Tutorials section would make them easier to find and provide a more task-oriented approach to learning.

For those familiar with earlier toolkit releases, tutorials could also serve to illustrate new approaches in recent toolkit versions, such as:

• Setting DITA-OT parameters with .properties files
• Embedding DITA-OT in other programs
• Installing and removing plugins

Please add comments below to suggest additional topics.

[shaneataylor]

I don't think I can assign this issue to myself (I see no affordance for doing so), but I'm working (in my fork) on topics for using the .properties files with the dita command.

Not sure precisely what is intended by creating a separate Tutorials section (my IA hat on says the top-level navigation would be more usable if divided among the main user goals — Installing the toolkit, Building deliverables, Extending the toolkit) but I definitely agree with orienting info around real-life user tasks & scenarios, and I'll use that approach.

[infotexture]

@shaneataylor: Thanks for picking up the .properties topics.

Self-assigning issues may require other permissions. I'll look into it.

Top-level nav reorg is also worth considering, once we have enough task-oriented content to support it.

[shaneataylor]

So, I've written some XSL to create an annotated template .properties file, and I have some example .properties files I want to use in the docs. I see two approaches to such example files in the existing docs:

• include the example / template files under samples in the dita-ot/dita-ot project
• include the example / template files somewhere in the dita-ot/docs project

There are many Ant sample files and templates in dita-ot/samples, and these are referenced in the docs. Yet, http://www.dita-ot.org/2.2/user-guide/creating-an-ant-build-script.html includes (albeit not by coderef — yet) an example Ant build that references files for building the documentation.

I like the idea of the examples we put forward being ones for which we supply files and that users could actually run and modify. But I think we should take a consistent approach so all such examples are located in the same place.

Creating, maintaining, and referencing sample files in the toolkit repo is currently more effort for contributors to the docs, but I think this might be the best place for them to exist for end users of the toolkit. One approach we could take to simplify this work would be to move all the existing samples files into their own repo, which could be incorporated as a submodule of both the dita-ot and docs repos, making example / sample files easy to find in the toolkit and easy to reference in the docs.

Opinions about this approach?

[infotexture]

Per discussions in dita-ot/dita-ot#2205 and #58, it makes sense to treat samples as part of the documentation and move them to the docs repo rather than adding a submodule to the dita-ot repo.

👍 for the idea of generating an annotated .properties file template. I suggest creating a separate pull request for those changes.

[osg]

I am currently mentally blocked at the end of the chapter 3: Building output using the dita command, which states, "Most builds require you to specify more options than are described in this topic."

How can I be involved in creating examples for this such as:

• Creating platform-specific output from the command line
• Creating audience-specific output from the command line

I need to know a few things:

• "What concept(s) do I need to be aware of?" [concept-based]
• "What pieces do I need?" [fact-based]
• "How can I practice this?" [practice-based]

[stale]

This issue has been automatically marked as stale because it has not been updated recently. It will be closed soon if no further activity occurs. Thank you for your contributions.