One challenge when working with technical information is that publications can be very large. Several hundred pages is not unusual and in some cases over a thousand pages are necessary to describe complex service procedures and part catalogs.
Authoring and assembling large books can be a painful process as the sheer size can be taxing to software. XML, DITA, and managing content objects do ease the pain, it is what industrial strength publishing software is designed to do. However, there is only so much information the average workstation can process.
Many creative solutions have been implemented to meet unique business requirements for book assembly. The business requirements and data sources vary from company to company, such as selecting lessons individually to create a complete custom course; or selecting individual part list and image pairs to create a complete part catalog. As an application expert, I have personally coded many custom solutions to support cobbling books together over the years and I know that many other equally creative solutions exist.
PTC’s Service Information Manager adds three advanced capabilities to the XML authoring and content management system:
- Translation Management
- Part List Generation
- Publication Structures
Publication Structures are the least sexy of the three and the one that truly revolutionizes the book assembly process. Publication Structures are used to assemble information objects that are to be published. Essentially each Publication Structure represents a book. You can add a table of contents, a parts list, or any other XML content object or images to the book right in the Windchill SIM web browser user interface.
Without Publication Structures, books are typically assembled manually in Arbortext Editor. Someone would still have to assemble the book manually in a Publication Structure, but the user experience is very different. To get a sense of this, in Arbortext Editor, if a writer wants to move a chapter to a different location, they would edit the document, select content, cut it, move to the new location, and then paste. In a Publication Structure, the user can drag and drop chapter or section objects in the structure without ever opening the book to edit it.
Publication Structures provide an out-of-the-box method of assembling publications for the technical documentation community without customizing. As a result, organizations are able to greatly improve the process of information delivery and are able to leverage dynamic publishing capabilities to bring products to market faster, and keep customers better informed.
Learn More
Refer to PTC’s web site for a complete description of Service Information Manager.
EAC information solution experts have decades of reliable XML solution experience. Explore the EAC website to learn more about our products and services or review the Product Development Information Services Brochure.
In the last few weeks I’ve discussed the benefits and costs of customization. This week I will review deciding whether to customize or not. If you missed these posts, you can read them here:
So how can you weigh the benefits against the costs of customizing? If we examine the criteria outlined above, a general pattern emerges, which provides the key insight in making this decision:
Benefits mainly go to end users, and costs mainly go to developers and administrators.
Installations with large user bases, where the value of customizations can be maximized, are good candidates for customization. Also, organizations that have dedicated staff for maintaining the Arbortext system will have an easier time managing customized installations than organizations where maintenance and development is a part-time task for staff with other responsibilities.
In organizations that have a small number of users, it will be difficult to realize enough value in customizations to make it worth the expense of implementing them. In these instances, it makes sense to stick with a mostly out-of-the-box installation using a standard doctype like DITA or DocBook, possibly with some stylesheet adjustments to get the desired output appearance.
Consider standard features first.
With all software, you can get the most value from your investment if you maximize the use of its standard features. If you are new to the software or perhaps not leveraging everything the software offers, you should explore the best practices and benefits first to determine if customization is truly needed. With Arbortext, PTC recommends an implementation approach called “Value-ready Deployment” which leverages the value of Arbortext using standard features and recommended best practices to maximize the value to each customer before any customizations are made.
Also consider prepackaged add-ons.
EAC offers several prepackaged add-ons which add capabilities to the Arbortext platform at a lower cost than a customization. One of our add-ons is EAC QuickPubs.
QuickPubs allows users to create aesthetically pleasing Operator Guides, Service Manuals, and Parts Catalogs quickly while providing an easy way to style documents that fit your brand. If you decide to investigate customizing Arbortext for your environment, EAC can help you explore your options with a variety of prepackaged add-ons, training, and implementation services.
Transform the way you design and publish product information through QuickPubs, an EAC product for PTC Arbortext. For more information about QuickPubs, you can download the brochure here. Publish faster, cheaper, and better today!
In my last post, ‘The Benefits of Customization,’ I told you I would review the cost of customization in my next post. If you missed it, you can find it here:
Of course, the benefits of customization don’t come without some associated costs. Here are some examples of the cost of customizing PTC Arbortext:
Development Costs
The most obvious cost is the cost of initially developing and testing the customization code. This will vary based on how extensive the customizations are. Also, don’t forget to keep maintenance costs in mind. Bug fixing, adding new features, and adapting customizations to changing requirements all require additional investment.
Version Lock-In
When you develop customizations, you generally work with a specific version of Arbortext. Depending on how extensive the customizations are, there is a chance that some part of the customization will break when you upgrade your Arbortext software to a new release version. In that case, you have two choices: either spend the resources to update the customization for the new Arbortext version, or commit to remaining with an out-of-date version of Arbortext to keep your customizations running.
Proprietary User Skills
With customization, you will need to take user training into account. For new features that don’t come out-of-the-box, you will have to develop your own training and support materials, and make sure your end users are up to speed on how to use the new features. In addition to the direct costs, this can also make recruiting new staff more challenging. There is a lot of DITA expertise in the marketplace, which you can leverage if you are using standard DITA. But if you are using a custom doctype and customized Arbortext Editor interface, you may not be able to get the same advantage from potential employees’ previous experience with XML editing or with Arbortext.
Technical Support Complications
PTC’s tech support staff know the base products quite well, and can help troubleshoot problems with out-of-the-box installations pretty quickly. However, with a heavily customized environment, troubleshooting can be more challenging, for PTC tech support as well as for yourself. In some cases, it may take extra time to determine whether a problem is due to a bug in the base Arbortext software, or something wrong with your customization code, or some kind of interaction between the two. In some cases, PTC’s advice for resolving the problem may boil down to “remove the customization.”
EAC has created a tool to help eliminate some of these costs allowing you to publish faster, cheaper, and better. QuickPubs is an EAC product for PTC Arbortext that removes the cost of development and provides a user-friendly interface.
While Arbortext comes with some publishing capabilities right out of the box, most users will acknowledge that they often need to customize the document stylesheets to meet their publishing standards. Customizing the stylesheets isn’t difficult, but it often requires prior training or hiring someone with the appropriate skilled and experience, both of which have an impact to turnaround time and cost. EAC has packaged attractive stylesheets for Operator Guides, Service Manuals, and Part Catalogs into QuickPubs so you can publish manuals that look as good as your products from day one. Should you need to modify the document stylesheet, QuickPubs also offers an easy interface to customize the style layout and formatting with a few clicks.
Stay tuned for the next post where I will discuss things to consider when deciding to customize or not.
If you would like to learn more about EAC QuickPubs and how you can publish faster, cheaper, and better, download the brochure here!
This is part one of a three part series regarding PTC Arbortext, deciding whether to customize or not. In this series, we will discuss the benefits of customization, the costs of customization, and deciding whether to customize or not.
You’ll often hear of DITA in the technical documentation world. DITA stands for ‘Darwin Information Typing Architecture’ -it’s an XML-based open standard for structuring, developing, managing, and publishing content. Quite the mouthful huh? What you need to know about DITA is that it leverages XML to be used as a way of writing and storing your data so you can manage it like an asset. What does it have to do with PTC’s Arbortext? PTC was the first company to ever deliver a complete DITA solution – one where organizations can finally start to maximize their investment in service lifecycle management.
One of the most fundamental questions you have to face when considering an Arbortext implementation is whether to use the technical documentation software out of the box or develop customizations to adapt the software to your specific use cases and work processes.
In practice, this is not so much of an either/or decision, as a how-much decision. In other words, nearly every implementation has some amount of customization, even if it’s just tweaking a composition stylesheet to add your own appearance specifications to the composed output. For some applications, where one of the standard doctypes such as DITA or DocBook is adequate, that’s all you need. For other applications, you may want to add custom features, user interface elements such as toolbars and custom dialogs, a tailored doctype or schema to support specific data requirements, connections to other enterprise systems such as ERP systems, and so on.
Adapting Arbortext software to your specific business environment can provide a number of advantages. Here are some examples where customization can add value to your implementation:
Author Efficiency
Custom features and user interface controls allow the author to work more efficiently.
Example: if authors frequently need to change one type of element into another similar element, then adding a toolbar button and/or keyboard shortcut to trigger the operation can let authors do it with a single click or key press, as opposed to using the Change Markup dialog.
Workflow Integration
Custom integration with software can streamline processes in the workflow.
Example: Suppose you have part data stored in an ERP system, and you are writing support documents associated with the part data. In a stock Arbortext installation, you might need to export the part data as an Excel spreadsheet, and then copy portions of the exported data in Excel to paste into the XML document in Arbortext. In contrast, a customization could allow authors to click a toolbar button, make a few quick selections in a dialog box, and automatically extract, format, and insert the part data in the correct location in the document.
New Capabilities
Customizations allow you to add new features to Arbortext Editor.
Example: Suppose you have a metric that you want to track on your documents that depends on the number of specific elements in each document, such as graphic elements. You can easily add a feature that would count instances of a specific element and report that for a document. You could also generate a report for a set of documents found in a directory tree or a folder in a content management system (CMS). This would let authors get this information directly within Arbortext Editor, without having to switch to an external tool to do the analysis/reporting.
This publishing engine software can be customized in a number of ways, and frequently we see users customizing their stylesheets to make them look better or compliant with their publishing standards. Arbortext stylesheets are used to publish documents that have consistent styling and formatting, no matter who authored the document. Sometimes these stylesheet customizations can be significant and complex, but often we see a need to make simple modifications to the fonts, logos, and page margins. EAC QuickPubs provides users an easy way to make those simple style modifications and create great looking documents.
Stay tuned for the next post where we discuss the cost of customization.
If you’re looking for ways to adapt your environment to fit your organizations needs, EAC QuickPubs may be for you. It’s an add-on designed to style documents that fit your organizations brand at a lower cost than a customization to PTC Arbortext. You can create aesthetically pleasing part manuals, owner’s guides, service manuals and more with ease. Publish fast, cheaper, and better today!
Transform the way you design and publish product information through QuickPubs, an EAC product for PTC Arbortext. For more information about QuickPubs contact us. Publish faster, cheaper, and better today!
For over 20 years I worked in the manufacturing industry as a designer, CAD or IT manager. One issue I have seen and experienced many times is the difficulty of getting upper management to understand the need and benefit of getting the latest CAD, PLM systems, or any other IT systems. In each role there was always the need for new software to keep my teams and systems as productive as possible. In this blog I will, at a very high-level, outline how I was able to get upper management to buy in on projects I felt were needed.
Very early in my career I was a CAD administrator. At the time we needed new CAD software. I was able to talk to upper management very often. I would try to explain and tell them the need. I would verbally walk through the benefits and even give them demos of the software. But… they would not want to pull the trigger on buying the latest software. I could theorize with them until I was blue in the face. It just didn’t matter.
Then, a mentor of mine recommended I put everything to numbers, such as creating a ROI and roadmap of what was required to implement the new software. So, I did. First, I did time studies against what we were doing today. I did this by getting input from various different users. This was basically recording how long it took them to do the most common tasks. I would always take multiple samples and then take the average. Then, using a trial install of the new version of software I was able to get comparisons for each use case tested against current software. I put the time savings to cost savings based on hourly rate averages. I also related it to increased engineering department output capabilities. For instance, our department could produce four projects a year. With the time improvements we can now produce five.
The next time I spoke with my manager, I simply put a one page short summary of total potential time and cost savings in front of him. Which in this case, immediately got his attention. He of course wanted to know how I came up with those numbers. I had to be ready to back my numbers up. I did this by giving him a more detailed page and walked him through my findings at a high-level. I also had a page outlining the general implementation roadmap with a timeline summary. Only three total pages, not a short novel. He could no longer just dismiss or put off the need. I received approval to proceed with my plan in less than a month after presenting my numbers to my manager. In this case my manager was one of the company owners, but having hard numbers and a tentative plan got the ball rolling.
One thing to note from the above example, by doing what I outlined above, it elevated my standing at my company. They were impressed at my willingness to push for, justify, and plan for something I believed in. Not just asking them to take on the burden of something I felt was a good idea.
This scenario was repeated throughout my career. I could bring in vendors to demo their product, put quote after quote in front of management. Meeting after meeting with vendors and upper management, I could not get management to agree until I took the time to document the true benefits in time and money (roadmap and ROI).
If you have product or process improvements you feel will benefit your company, you need to show your management that you truly believe in it. You need to do the needed research and documentation to show the benefit and how you recommend proceeding. You cannot just go and tell management there are problems. You must present a solution for the problem you are identifying. If you do this extra work, it will not only help get your request approved, but will also help how you are viewed by your management.
Look, I know what I am outlining is no small task. It can be time consuming, very time consuming in some cases. That’s why many times this never gets done and needed improvement projects never happen. There is just not enough time for internal staff to do the needed research, and get their day-to-day tasks done as well. That is why you need to partner with a company dedicated to help with product development improvements at your company, such as EAC. We don’t want to just sell you software, we want to help you and your company improve the way you design, manufacture, connect to, and service your products. We do this with our proven people, products and processes. If you and your company improve and succeed, we improve and succeed. We will do as much of the work as we can to help you get the needed numbers and roadmaps put together. There is always going to be some time needed from internal people. However, we try to keep this as minimal as possible.
In summary, if you can see areas where your processes or systems could be improved you need to put it to numbers. You need an ROI and a roadmap to take to upper management. It may seem frustrating at times, but you need to understand where management is coming from. They also have people they answer to. They can’t go to a board, or an owner, or their manager with just a demo and a quote. Not only is that not the information they are concerned with, but you typically don’t get that type of time with them. They need quick and real information to justify the need. You must be willing and ready to get this for them. Just remember, EAC is here to help you do this. Please reach out to us.
This tutorial is a follow-up to my previous tutorial, “Getting Started with the Arduino Uno and ThingWorx.” Connecting to ThingWorx with the Arduino is easy if you possess an Ethernet or WiFi Shield but you can still connect without one! Using the Processing language you can send data from your Arduino to a computer via a serial connection and push it to ThingWorx.
Requirements:
- ThingWorx hosted instance
- Arduino Uno
- Processing Environment (found at Processing.org)
- Arduino Environment
In this post:
Introduction to Processing:
Processing is the language that the Arduino language is built on. This means that the syntax is very similar. I would recommend visiting the tutorials and documentation that is provided on the Processing.org site as it is very informative and helpful.
Tutorial:
In order to push data to your ThingWorx thing refer to my previous tutorial, “Getting Started with the Arduino Uno and ThingWorx,” to get a Thing and Service set up. Next, copy and paste the example code that is included with this post. That’s really all you need to do!
More specifically, enter all of your pertinent server and thing information into your processing code. You should now be ready to start pushing data to ThingWorx. Fire up your Arduino and upload the example code to it. Next, push the “play” button at the top of your Processing Environment.
You may run into a few issues. One, if your Processing code throws an error about your serial port (it will say something about a “null exception”) you’ll need to determine which serial port your Arduino is at. The Processing code will print a list of available ports and default to the first one on the list. If your port is different then you can change it in the code:
You can either change the highlighted number to match the position that the port is listed or just change the highlighted variable portName to the actual name of the port:
You will also have an issue if you try and open your Serial Monitor in your Arduino Environment. This will cause your port to become unavailable.
Advantages and Disadvantages: Now that you know how to connect your Arduino to ThingWorx using three different methods, let’s discuss some possible advantages and disadvantages of each. In the case of the Ethernet Shield, you are able to move from one network to another without much issue. No new coding is needed. With the WiFi shield, you must recode your Arduino any time that you switch networks so you can enter the SSID and Security Code if needed. However, once the Arduino is configured correctly, you merely turn it on and it runs as a standalone device.
The serial connection allows you connect to the internet without the use of a shield. The cost of an Ethernet or WiFi shield is typically between $30 and 80$ depending on the manufacturer. A disadvantage is that you must be tethered to the Arduino with a computer if you want to send data.
The Processing language is very easy to learn and there are tutorials on the web that will instruct you on how to build user interfaces that you can control your Arduino with. This makes the serial connection an attractive option if you want some control over pins or variables on your Arduino!
And now for some code…
/***************************************************************************************************
ThingWorx Serial Example for Arduino Uno
This Arduino and Processing code allows you to connect to ThingWorx without the use of an Ethernet
or WiFi Shield. The data is sent from the Arduino to the computer via the serial (USB) connection
to your computer. All server and “Thing” data goes into the Processing code that is commented out
at the end of the Arduino Code. When you are running this code do NOT use the Serial Monitor in the
Arduino environment as it will interrupt the Serial connection to Processing. The Processing language
can be found at Processing.org.
Created by Nick Milleson
Design Engineer
EAC Product Development Solutions
nmilleson@eacpds.com
***************************************************************************************************/
//Make sure that SENSORCOUNT matches SENSORCOUNT in the Processing code
#define SENSORCOUNT 4
double sensorValues[SENSORCOUNT];
//Denote the pins you will be using
int sensorPins[] = {A0, A1, A2, A3};
void setup() {
//begin Serial connection
Serial.begin(9600);
for (int idx = 0; idx < SENSORCOUNT; idx++)
{
pinMode(sensorPins[idx], INPUT);
}
}
void loop() {
//Read info from the pins
for (int idx = 0; idx < SENSORCOUNT; idx++)
{
sensorValues[idx] = analogRead(sensorPins[idx]);
}
//send out a serial message that tells your Processing code that you are beginning a transmission
Serial.println(“begin”);
for (int idx = 0; idx < SENSORCOUNT; idx++)
{
//Send data over the serial port
Serial.println(sensorValues[idx]);
}
delay(1000);
}
/***************************************************************************************************
ThingWorx Serial Example for Arduino Uno
This Arduino and Processing code allows you to connect to ThingWorx without the use of an Ethernet
or WiFi Shield. The data is sent from the Arduino to the computer via the serial (USB) connection
to your computer.
Enter your Server, appKey, Thing, Service, and sensorNames to match up with the data being sent by
the Arduino. Make sure that you do NOT use the Serial monitor in the Arduino Environment. It will
disrupt the connection.
For a tutorial on creating your Thing and Service, visit:
Getting Started with the Arduino Uno and ThingWorx
https://www.eacpds.com/product-development-system-blog/getting-started-with-the-arduino-uno-and-thingworx/
Created by Nick Milleson
Design Engineer
EAC Product Development Solutions
nmilleson@eacpds.com
***************************************************************************************************/
/*
import processing.net.*;
import processing.serial.*;
Client myClient; // Client object
Serial myPort; // The serial port
final int SENSORCOUNT = 4; // This value must match SENSORCOUNT in your Arduino Code
String sensorValues[] = new String[SENSORCOUNT];
String junk;
String beginString = “begin”;
String myServer = “enter server here”;
String appKey = “enter appKey here”;
String thingName = “enter Thing here”;
String serviceName = “Enter Service here”;
String myURI = “POST /Thingworx/Things/” + thingName + “/Services/” + serviceName + “?appKey=” + appKey + “&method=post&x-thingworx-session=true<“;
String myHost = “Host: ” + myServer;
String myContent = “Content-type: text/htmln”;
String sensorNames[] = {
“valueOne”, “valueTwo”, “valueThree”, “valueFour”
}; //Enter your variable names (these must match the inputs in your Service)
void setup() {
// Print a list of the serial ports, for debugging purposes:
println(Serial.list());
String portName = Serial.list()[0];
myPort = new Serial(this, portName, 9600);
myClient = new Client(this, myServer, 80);
}
int idx = SENSORCOUNT + 2;
void draw() {
if (myPort.available() > 0)
{
junk = null;
junk = myPort.readStringUntil(‘n’);
// look for the initial “begin” string that Arduino sends
if (junk != null)
{
if (beginString.equals(trim(junk)))
{
junk = null;
idx=0;
}
}
//Read each sensor value
if ((junk != null) && (idx < SENSORCOUNT))
{
sensorValues[idx] = junk;
junk = null;
idx++;
}
//When all sensor values have been read, send the info to ThingWorx
if (idx == SENSORCOUNT)
{
myClient.write(myURI);
for (int index = 0; index < SENSORCOUNT; index++)
{
myClient.write(“&” + sensorNames[index] + “=” + trim(sensorValues[index]));
}
myClient.write(“> HTTP/1.1n”);
myClient.write(myHost + ‘n’);
myClient.write(myContent + ‘n’);
println(“Sending this REST call:”);
print(myURI);
for (int index = 0; index < SENSORCOUNT; index++)
{
print(“&” + sensorNames[index] + “=” + trim(sensorValues[index]));
}
print(“> HTTP/1.1n”);
print(myHost + ‘n’);
print(myContent + ‘n’);
print(‘n’);
idx = SENSORCOUNT + 2;
}
}
}
*/
