PDX DITA is starting a DITA Book Club in January 2016, open to anyone interested in reading and discussing DITA Best Practices.
All levels welcome!
If you are new to DITA, learn along with us!
If you have DITA experience, join us in looking at the basics from a new perspective.
Where: Jive Software, 915 SW Stark Street, Portland, OR
When: January 20, 2016 from 5:00 to 6:00 pm
What: Chapters 1 and 2 of DITA Best Practices
We are looking to schedule future DITA Book Club meetings on the third Wednesday of every month. Information about future meetings will be posted on this website.
Please note, this meeting time will be reserved for discussing the latest two chapters in DITA Best Practices. If you have general questions and interest in DITA, please attend one of our regular quarterly meetings!
At our October meeting last week, Roger Hadley and the technical communications team at Fiserv, a global financial service company with an office in Hillsboro, presented to a full house of PDX DITA users from such companies as Cisco, NetApp, InfoParse, and Harmonic.
Roger walked us through Fiserv’s implementation of faceted search that relies on DITA metadata and a SQL search server to search their 5,000 help topics. There is one search box to enter search terms and results are listed in a center pane containing links to help topics; you can further refine the results using filters shown in the left sidebar that are based on their metadata labels of Feature, Function, and Role.
This awesome project took:
- A team of 8 (5 writers, 1 lead, 1 architect, and 1 manager)
- One year of planning
- One year to implement
And some quick stats about their documentation ecosystem:
- 5,000 xml topics
- 6 product categories (each built from their own map)
- Hundreds of conrefs and keyrefs embedded in the xml files
- Filters based on the following:
- Feature — 34 keywords
- Function — 90 keywords
- Role — 20 keywords
Planning and Implementation
To complete this project, the team:
- Researched what their users needed from a better search experience (they had been hearing over the years that the search was getting worse and worse as their content was increasing)
- Determined that a DITA metadata/SQL Search Server approach could yield a simpler and more accurate search experience
- Decided that faceted search based on their existing tags for Feature, Function, and Role would best optimize search results for their particular content set
- Created a homegrown utility that showed their Feature, Function, and Role tags so writers could easily add them to the top of each xml file
- Manually edited all 5,000 help topics and tagged them with the appropriate Feature, Function, and Role metadata attributes
SQL/MS Search Server Work
The team used Microsoft Search Server Express to index pages based on their metadata. A SQL index file built during the XHTML transformation for each map/product, is used to populate a database of pages for each product. Breadcrumbs, navigation, and metadata-based search links are added to each content page based on the information in the SQL database, as well as the metadata in each page, via PHP.
Microsoft Search Server Express offered some built-in features that they used out-of-the-box or with relatively straightforward customization, such as:
- Provides a single box on the search home page to enter search terms (which then searches all 25,000 topics)
- Shows a list of search results in the form of links to help topics below the search box
- Builds a TOC-like hierarchy in the left sidebar based on Feature, Function, and Role which you can refine results by
We hope you’ll join us December 2nd when we host a joint meeting with our local chapter of Write the Docs.
We’re excited to announce that PDX DITA member, information architect, content strategist, Portland State instructor, and general bon vivant Toni Mantych will be teaching a two-day workshop called DITA for Authors on May 9 and 10th, 2014. The workshop is focused on authoring skills, and is aimed at people who already understand the importance of DITA and its value proposition, but don’t yet have extensive hands-on experience in the authoring medium. It will cover basic authoring knowledge like topic types and element use, but also will get into conditional filtering, keyrefs and conrefs and how to get the most value out of your content. Sounds extremely useful!
Full details are here: Dita for Authors