DITA-OT
DITA init: Best practices for project setup
#4523
Replies: 4 comments
-
|
So the profile of user who would benefit from this feature would be the one of an end user who has never used DITA XML before. They do not have a DITA XML editing tool, they download the publishing engine (which needs to be run from a command line) and they have no DITA project on which to run it (because if they did have a DITA XML project they would want to rectify that project and not create a sample project). I think there are very few people who would fit this profile. Putting myself in this perspective I would probably not expect a publishing engine/pipeline to produce for me based on best practices the startup sample project on which it can later run itself. Maybe I would expect in the DITA OT documentation to find a page with useful resources and some information about a DITA XML project's structure and best practices. So having the DITA OT generate a sample project based on best practices is a nice to have but not sure how many people it would impact. Most people start learning DITA XML from a tutorial and by first writing the XML, not by first downloading the publishing engine. I think the DITA OT can break through the niche in which it is by fully embracing the Markdown publishing capabilities. There are Markdown users who want to produce quality PDFs and to customize them. A Markdown user who already has a project written in mkdocs for example I think would appreciate if the DITA OT would interpret the "mkdocs.yml" file directly as a DITA Map or would produce an equivalent DITA Map in the existing markdown project so that it can use that DITA Map to produce a PDF. |
Beta Was this translation helpful? Give feedback.
-
|
@infotexture this was a big pain in the ass for us as well. Unfortunately the best way to do this depends on some company specific factors:
These were the main influencing factors for us. Our solution works for us, but might not work for others. This architecture properly scales until the boundaries of a Git repository. Because setting up a new document/model implies the creation of a lot of files and directories, we have created a wizard, which is basically an XML file with metadata and an Apache Ant script to create this structure, enriches the metadata in maps and topics, copy and pastes map and topic templates, and so forth. |
Beta Was this translation helpful? Give feedback.
-
|
#4509 has been merged and it now makes it possible for plug-ins to contribute named init templates. I created |
Beta Was this translation helpful? Give feedback.
-
|
FWIW, we've been using a home-grown repo-branch provisioning Jenkins job that prompts the user for several values that are used by a Python script to replace placeholder strings in various files from a template project in Git with a suggested directory structure. In our case, the placeholder strings are in pom.xml, build.xml, Jenkinsfile, properties files, and other config files. Since it's run from a Jenkins job, the Python code commits and pushes the changes to the new branch(es) that were requested. Allowing a plugin to contribute templates is a flexible way for companies to implement whatever they need.. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Following up on an idea from the July contributors’ call:
One of the things new DITA users struggle with is how to organize files.
The requirements can differ widely based on the project size, company habits, number of products/variants, localization considerations, platform limitations, version control system conventions, etc.
Given this variety, there’s no universally accepted “best” practice for project structure, so we haven’t offered much in the way of recommendations thus far.
But this makes it hard for people to get started. If they haven’t used DITA before (or are setting up a project from scratch for the first time), they may not know what questions to ask, or which patterns have proven useful in similar projects.
Implementing a basic docs-as-code setup is a common use case in small teams: if you’re using Git as your CMS, and a toolkit and plug-ins on your file system, how would you lay it out?
Could DITA-OT help users to set this up?
How might we provide guidance on things like:
Others have written about this in the past, but the information is somewhat scattered, and old enough that people may question whether it applies to recent toolkit versions:
DITA For Small Technical Documentation Teams
This links to oXygen’s sample project skeleton repository:
dita-project-best-practices
What if we had a
dita initcommand that would prompt users for a few details about their project, and create a sample project layout based on the responses?What questions would we need to ask there to derive a basic folder hierarchy?
Depending on the user’s responses, would we recommend something like ↓ this?
— What other variations should we anticipate/propose?
Would we use an approach like boilr to define sample project layouts in repositories that can be selected based on the user’s responses?
If a company has a standard file system layout they want to use in all projects, how would they define that in a way that DITA-OT could access and apply?
Share your thoughts in the comments to let us know whether this idea is something you’d find useful, and what sort of structure you’d want to apply.
See also:
Beta Was this translation helpful? Give feedback.
All reactions