Part 4: Top Three Resources for Arbortext Users

This is part four of the four-part series

If you're an Arbortext User, you should know about these resources:

1. Mailing list hosted by PTC/User
   
   The PTC/User portal (http://www.ptcuser.org) hosts the long-running Adepters mailing list. Arbortext engineers monitor the list as well as many long-time users and tools folks. If you have a question, it's a really good resource.
   
   The List Email Address is: adepters@lists.ptcuser.org
   
   You can join the list from the PTC/User portal: http://portal.ptcuser.org/index.php?mo=fo&op=si
   


2. The Adepters Information Archive
   
   The Adepters Information archive is located here http://www.adepters.org.
   
   Many Arbortext users regularly search it for help with difficult to solve issues. The archive was started by Karl Johan Kleist. In 2008, Karl changed career paths, and I've been maintaining it ever since..
   


3. Mailing List hosted by Yahoo Groups
   
   Yahoo Group Name: 3b2users
   
   3b2users is a list for users of Advent 3B2, now called Arbortext Advanced Print Publisher, for the exchange of information, hints and tips.
   


4. Introduction to DITA: A User Guide to the Darwin Information Typing Architecture Arbortext Edition - JoAnn Hackos
   
   Although not an online resource, this is Arbortext-specific. Procedures and Examples in this book use Arbortext Editor.
   

Read the complete series:

1. Part 1: Resources for folks doing single-sourcing projects


2. Part 2: Top 6 book choices


3. Part 3: Top 12 online topic-specific resources


4. Part 4: Top 4 resources for Arbortext users.

Part 3: Top 12 resources for XML authoring and publishing projects

This is part three of a four-part series.

These resources are good for folks who are getting started on XML or SGML authoring and publishing projects or who are in the middle of one.

1. singlesourcing-mgmt
   
   Singlesourcing-mgmt is a moderated mailing list for those interested in the management of single sourcing and related topics Single-Sourcing
   


2. xml-doc
   
   xml-doc is a mailing list where writers, developers, product and service vendors, and others discuss the application of XML, SGML, and related technologies to structured authoring, particularly authoring of documentation for computer software and hardware.
   


3. comp.text.xml
   
   The Extensible Markup Language (XML).
   


4. comp.text.sgml
   
   ISO 8879 SGML, structured documents, markup languages
   


5. dita-users
   
   This group supports users of DITA.
   


6. Docbook.org
   
   This is the official home page for all things Docbook.
   


7. S1000D Users
   
   S1000D Users Google Group is an online community for people who want to learn more about S1000D and related standards from other professionals. The idea is to form a peer organization focusing on the practice of sharing experiences, issues and collaborating with members worldwide.
   


8. svg-developers
   
   This is a mailing list for anyone who is interested in developing SVG content, or in helping others solve development problems in either the SVG format or in scripting. Discussions tend to be very technical.
   


9. XSL Mailing List
   
   The open forum for the discussion of XSL -- Extensible Stylesheet Language.
   


10. XSL-FO
    
    XSL Formatting Objects discussion group. All questions are welcome. As the group grows hopefully we can share our experience and growing knowledge.
    


11. ZVON Repository
    
    The best online library for specific XML-related technology. They have a Reference Library and Tutorials.
    


12. svdig
    
    Although this is the mailing list for the local Silicon Valley DITA Interest Group (SVDIG), lots of good information shows up here as well.
    

Read the complete series:

1. Part 1: Resources for folks doing single-sourcing projects


2. Part 2: Top 6 book choices


3. Part 3: Top 10 online topic-specific resources


4. Part 4: Top 4 resources for Arbortext users.

Part 2: Top 6 books for people starting XML/SGML publishing projects

This is part two of a four-part series.

I have never found the one book that describes how to put it all together. These are the top 5 books, I'd recommend to anyone starting a single-sourcing project. They're a selection of books from both sides of the issue: the writing side and the programming side. Together, they begin to bring any project into focus.

1. The XML Handbook (2nd Edition) - Charles Goldfarb & Paul Prescod (Prentice Hall:2000) (ISBN: 0130147141)
   
   All about XML.
   


2. Definitive XSLT and XPath - G. Ken Holman (Prentice Hall:2002) (ISBN: 0130651966)
   
   This is the ultimate xlst & xpath book.
   


3. Definitive XSL-FO (Charles F. Goldfarb Definitive XML Series) - G. Ken Holman (Pearson Education:2003) (ISBN: 0131403745)
   
   The authority for learning XSL-FO
   


4. Developing SGML DTDs: From Text to Model to Markup - Eve Maler & Jeanne El Andaloussi (Prentice Hall PTR:1996) (ISBN: 0133098818)
   
   Although this book is written about SGML, the basics for data modeling are all here and apply to XML projects as much as to SGML projects. This is a great basic data modeling beginner's book.
   


5. Single Sourcing: Building Modular Documentation - Kurt Ament (Noyes Data Corporation/Noyes Publications:2002) (ISBN: 0815514913)
   
   An excellent book for people staring single-sourcing projects. How to plan and implement as well as how to handle the inevitable staff issues.
   


6. Introduction to DITA: A User Guide to the Darwin Information Typing Architecture Arbortext Edition - JoAnn Hackos
   
   Procedures and Examples in this book use Arbortext Editor.
   

Read the complete series:

1. Part 1: Resources for folks doing single-sourcing projects


2. Part 2: Top 6 book choices


3. Part 3: Top 12 online topic-specific resources


4. Part 4: Top 4 resources for Arbortext users.

Resources for Single-Sourcing Projects (Part 1 of 4)

This is the first post in a four-part series.

Folks starting single-sourcing projects are faced with insufficient resources. The biggest problem with the existing literature is that nearly all of it is theoretical in nature. Most books on single sourcing contain advice about planning, managing, and creating modular projects and documentation. At this, they are very good. What they’re all missing is the bridge between theory and practice. And they’re not alone.

I have found that most of the single-sourcing literature is aimed at writers or managers, not implementers. I created this list when I was hired on my first single-sourcing project. I was hired to design and implement not to manage. I wouldn’t be selling upwards: my director was championing this project throughout the company. Someone else would be doing that. Someone else would be determining ROI and measuring success. Nor was I the project manager, even though I would help determine which tools we eventually choose.

What was not aimed at managers was aimed at writers: guidelines for writing and designing modular documentation. This is something else that I would not be part of and should not be. The writers who would be using the single sourcing system would be planning their documentation, just as they always did. This sort of information was valuable as a look at the point of view of the user, but it wasn’t what I was looking for as an implementer. But I knew that these books would be essential for training the writers to write and think modularly.

The programming literature is nearly as bad. The XML programming book that don’t describe its implementation as a language describe the multitude of ways you can use XML. They tell you how to write the XML and how to process it: They do not tell you how to make XML work in a single sourcing environment. In addition, the programmer-oriented books are not aimed at either of the groups that the single sourcing documentation targets. XML authors assume their readers have a programming background and already understand programming concepts.

I have never found the one book that describes how to put it all together. You make choices—good and bad—along the way that influences the way you implemented particular pieces. You choose a set of tools. You do as much or as little customization as you're comfortable with and as your goals require.

My goal has always been to provide specific examples that can serve spark ideas to solve someone else’s real problems. That is the best any case study can do: Give you an idea about what you can try. Hopefully, all together, these resources will help bring your project into focus.


Stay tuned for the next parts in the series:

1. Part 2: Top 6 book choices


2. Part 3: Top 12 online topic-specific resources


3. Part 4: Top 4 resources for Arbortext users.

Starting a User Group

We're doing our best to start a local PTC/User chapter in the San Francisco Bay Area. We have setup a MeetUp page and are preparing to launch this organization in coordination with the national PTC/User organization. When Arbortext was acquired by PTC, a lot of things changed for existing Arbortext customers. We were used to speaking directly with Project Management and with Developers (when necessary), and we had a strong and successful relationship with our Sales Representatives. After the acquisition, this changed dramatically. Sales Reps were replaced by VARs and many support calls were replaced by proposals for consulting work by PTC.

A lot of this has to do with the way PTC has traditionally done business. It also has to do with the separation between PTC and PTC/User. In this new structure, PTC expected that much of the user support and interaction for simple questions and implementation issues would be handled between users at local RUGs (Regional User Groups), through mailing lists, and the online PTC/User bulletin board.

After two years of adapting to the PTC world view and after becoming a PTC partner, we finally understand how to improve the experience of PTC/Arbortext users: We have decided to start one or more local user groups, to support the regions that our partnership with PTC defines. The SFBay RUG is the first. If you're in the SFBay, and you want to be a part of this group, please see the meetup page. Local customers will also be receiving an invitation from the PTC Channel Sales manager. If you're in another region, we'll do what we can to help you get a RUG started in your area, too!

SF Bay Meetup Page