This topic provides answers to frequently asked questions from real AgilePoint users about the AgilePoint NX product documentation.
As of the initial release of AgilePoint NX v7.0, the product documentation includes over 5,200 HTML articles and 14 PDF documents. The documentation is updated about every 2 months with new articles, and fixes and enhancements for existing articles.
Our goal is to thoroughly document all functionality in AgilePoint NX. However, the product documentation focuses on several main content areas, which customer feedback over the last 10 years has told us are the most important to our users:
Currently, the documentation is also adding more use case examples in response to user feedback. More information is provided about this effort in the sections below.
The AgilePoint NX product documentation is divided into two main documents:
Both the Online Help and Technical Documentation include 2 common sections:
One example of this functionality is the activity topic. "Activity" is a term that is specific to AgilePoint NX, but other products may call a similar feature "task", "shape", "widget", and so on. You can search for "shape" or "widget," but find the "activity" concept topic.
Concept topics are linked throughout the documentation with links that display in black underline — for example, database. These links can help you quickly find the meaning of an unfamiliar concept, or find out more information about that concept if the current topic does not answer your question about it.
To find information in the documentation quickly:
AgilePoint NX documentation does not support natural language search, such as search results based on a question. Simple search terms work best.
The resulting topic (eForm, in this example) will provide you with a list of related topics that serves as a kind of consolidated search results page related to that topic, including troubleshooting articles. It will also provide a list of examples and videos related to the topic, if they are available.
If you are looking at the AgilePoint documentation, chances are you are trying to solve a specific problem. There are several ways to get troubleshooting information:
Most of the examples in the AgilePoint NX documentation can be found in the section How-To Examples. Any documentation topics that have related examples provide a section titled Examples with links to the example topics. Example topics are also usually indicated in documentation search results with the text (Example) in the page title.
This is by far the most frequent question we hear from AgilePoint users regarding the documentation. For the last several years, we have been adding new examples to the AgilePoint NX documentation with every release. This is an effort we are expanding at an ever-accelerating pace.
We understand from user feedback that AgilePoint users want examples for many types of tasks. More specifically, users tell us that they don't just want basic or general examples, but real-world examples that are relevant to their own use cases and business problems. The biggest challenge with meeting this need is that AgilePoint NX is industry-agnostic. A realistic business scenario in the automotive industry may be irrelevant for an AgilePoint NX user who works in finance, retail, education, or government. Unfortunately, it simply is not feasible to provide example documentation for every possible use case for every industry that AgilePoint supports. For help with your specific use case, we recommend the AgilePoint Community Forums, Product Training that can be tailored to your needs, or mentoring from Professional Services.
Another challenge related to providing realistic examples is that real-world use cases are complex. They require understanding the business case for the example (which many users do not care about), and they often require a large number of setup steps in order to get to the specific functionality a particular user is interested in at a particular time. We have found through experience, user feedback, and observations of user behavior that documentation for realistic use cases often requires more explanation and setup than people are willing to read or navigate through. In other words, even though we receive a large number of requests for real-world use case examples, we have found that in practice, actual users do not tend to use detailed documentation for real-world examples because it is too difficult to find the specific information they are looking for. This may seem counterintuitive, but the data we have collected over 10 years of user feedback and observation suggest this tends to be the case for the majority of AgilePoint NX users.
It is further worth mentioning that this issue is not unique to AgilePoint as a company. Example-based documentation is not generally considered a software industry best practice for formal product documentation for the same reasons that AgilePoint NX documentation is not primarily example-based. Other reasons for this include the challenges related to keeping detailed examples updated over time. For these reasons, real-world use case examples tend to be better suited for one-time publication formats that do not need to be kept up to date, such as training, videos, blogs, and user discussion forums, than they are for formal product documentation, which is expected to always reflect the most recent changes to the software. A well-known example of this is the developer documentation from Microsoft. The official product documentation on MSDN does not, for the most part, provide detailed use case examples for every type of task. Instead, examples are provided mainly through user forums and blogs. AgilePoint takes a similar approach.
With that said, starting with AgilePoint NX v7.0, AgilePoint users have access to a range of free sample applications through the App Store. The AgilePoint documentation will be leveraging these free apps to provide more use case examples that require minimal setup.
AgilePoint provides a limited number of documents in PDF format. These are mainly the documents that are the most commonly requested when people are evaluating or installing the AgilePoint NX product. You can find links to all the PDF documents on the Technical Documentation home page.
In the AgilePoint documentation, we try to provide as much information as possible about all AgilePoint NX functionality. However, there are some limitations regarding the information we are able to provide for third-party product integrations, such as Salesforce, SharePoint, Microsoft Azure IoT, and so on.
Third-party companies provide their own, detailed documentation regarding the concepts and functionality for their products. AgilePoint is not able to repeat all the information provided for all third-party products. Instead, we refer you to the documentation for the third-party products themselves.
Specific limitations in AgilePoint documentation for third-party product integrations include the following:
For example, many third-party products use some version of entities, records, fields, and similar, related concepts. AgilePoint documentation explains what these concepts mean for AgilePoint NX products, such as in the Data Entities or eForm Builder components, but we do not typically explain all of the nuanced differences about what these concepts mean in other products AgilePoint integrates with, such as Salesforce, NetSuite, OData, and so on. That information is the responsibility of the third-party software providers.
In short, providing detailed information about the input fields for third-party products is primarily the responsibility of the third-party software providers. AgilePoint documentation focuses on information about the logic and functionality of the AgilePoint NX UI and how this might change the information typically required from third-party providers.
In most cases, these limitations make it unfeasible for the AgilePoint NX product documentation to provide detailed examples for third-party integrations.
If you have questions about specific use cases for integrating third-party products with AgilePoint NX, we recommend you search or post a question in the AgilePoint Community Forums. Other AgilePoint users who use similar integrations may be better able to answer your specific questions or provide real-world examples of solutions they have created.
Some parts of the documentation have a lot of detail, while other parts are lighter on details. There are several reasons for this, depending upon the context:
Throughout the documentation, many links open in a new tab or window. This is to accommodate the fact that there are two separated sections in the AgilePoint NX documentation (Technical Documentation and Online Help), but these sections often require cross-linking. We found through usability testing that if we sent users to a link from the Technical Documentation to the Online Help within the same tab, people often got lost because it is difficult to tell that they changed documents.
Even though this resolves the issue of losing one's place when documents are cross-linked, we understand that this functionality is still frustrating for many users. We are evaluating alternative navigation schemes to resolve this issue, and we expect to provide significant enhancements related to this in a future documentation release.
More than half of AgilePoint NX users are located outside the U.S., and it is estimated that many more do not speak English as a first language. To help these users, AgilePoint documentation uses an English language standard called Simplified Technical English (STE). STE uses a limited, standardized, international English language vocabulary of words that have been scientifically demonstrated as the most likely to be understood by people who speak English as a second language. It also eliminates words that do not have direct translations in many non-English languages, such as contractions and verbs that end in -ing. This helps AgilePoint users outside the U.S. understand the documentation, and it facilitates more accurate translation through automated translation systems, such as Google Translate. The trade-off for native English speakers, especially in the U.S., where modern English usage tends to be less formal, is that documentation written in STE can sound formal, unnatural, simplistic, or outdated.
We welcome feedback on the AgilePoint documentation, and we listen to every comment and request that is submitted from our users. You can submit feedback on the documentation by sending an e-mail to email@example.com. Documentation feedback does not count against your contracted number of support tickets.