This topic provides answers to frequently asked questions from real AgilePoint users about the AgilePoint NX product documentation.
Is AgilePoint NX thoroughly documented?
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:
- Detailed definitions for UI configuration fields
- Server-side administration
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.
How is the AgilePoint NX documentation organized?
The AgilePoint NX product documentation is divided into two main documents:
- Online Help - Information about the AgilePoint NX Portal and components that apply to all versions of AgilePoint NX.
- Technical Documentation - Information that applies only to AgilePoint NX OnPremises and PrivateCloud, such as AgilePoint Server configuration and APIs.
Both the Online Help and Technical Documentation include 2 common sections:
- Troubleshooting - Topics that explain how to resolve common issues or perform tasks that cross over between the Technical Documentation and Online Help, or cross between multiple product components, such as Offline Mobile eForms.
- Concepts - A collection of topics that provide 3 main functions:
- Basic information about technical concepts that are used in AgilePoint NX documentation.
- A list of related topic links, examples, and videos related to the concept.
- A list of related keywords that facilitate fuzzy language search.
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.
What is the fastest way to find information in the AgilePoint documentation?
To find information in the documentation quickly:
- Open either the Technical Documentation or Online Help.
- In the Search box, enter a simple search term, such as eForm.
AgilePoint NX documentation does not support natural language search, such as search results based on a question. Simple search terms work best.
- In the search results, click the link that is the closest to your search term — in this case, eForm.
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.
Where can I find information about troubleshooting?
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:
- For the basics, refer to A Basic Guide to Troubleshooting AgilePoint NX Errors.
- The documentation includes an extensive Troubleshooting section with over 300 topics.
- Any part of the AgilePoint documentation may be relevant for troubleshooting, depending upon what problem you are trying to solve. Refer to the section, What is the fastest way to find information in the AgilePoint documentation?
- Search or post a question in the AgilePoint Community Forums.
Where can I find examples?
Most of the examples in the AgilePoint NX documentation can be found in the Examples section. 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.
Why aren't there more examples in the AgilePoint documentation?
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.
Where can I find PDF versions of the documentation?
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.
How does the documentation support third-party integrations?
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:
- Third-Party Concepts - Unless it is critical to understand how the AgilePoint NX software operates, the AgilePoint documentation typically does not explain the technical concepts in third-party products.
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.
- Field Definitions for Third-Party Products - One of the main goals of the AgilePoint documentation is to provide as much detail as possible for every UI field in the AgilePoint NX product. This is an area we are constantly working very hard to improve because we know it is one of the most common reasons people use the AgilePoint documentation. However, we are not able to provide as much detail for fields related to third-party integrations as we are for native AgilePoint NX functionality. This is because:
- Most of this information is documented by the third-party companies themselves, often in great detail. Reproducing this information in the AgilePoint documentation is not practical.
- AgilePoint does not have direct access to third-party technical resources to gather information about the behavior of input fields in same ways that we have direct access to our internal resources.
- Third-party vendors can (and do) change their functionality and documentation without notice to AgilePoint.
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.
- Examples - Even though we are expanding the examples available in the AgilePoint documentation, it is unlikely that we will add a large number of examples related to third-party product integrations. There are several reasons for this:
- Realistic examples that use third-party integrations often require extensive setup in the third-party systems, which requires specialized domain expertise regarding best practices in those systems. AgilePoint provides this kind of specialized domain knowledge through Professional Services, rather than product documentation.
- Third-party system configurations must be maintained indefinitely over time in order to keep example documentation up to date. Real-world experience has shown that in most cases, this is not feasible.
- There is a wide range of use cases for third-party products that AgilePoint cannot predict or accommodate in example scenarios. Examples of this challenge include Salesforce environments, in which organizations tend to create their own, unique ecosystems, and Microsoft Azure Bot Services, which requires organizations to create their own custom-coded apps.
In most cases, these limitations make it unfeasible for the AgilePoint NX product documentation to provide detailed examples for third-party integrations.
Where can I find more information about integrating AgilePoint NX with third-party products?
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.
Why do some parts of the documentation have more detail than others?
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:
- Different parts of the documentation are intended for different audiences — for example, some documentation is mainly for highly technical users, while other information is for users who are new to AgilePoint NX, or who have limited technical knowledge.
- Documentation for third-party integrations have less detail than the documentation functionality that is native to AgilePoint NX. For more information, refer to the section, How does the documentation support third-party integrations?
- The AgilePoint documentation has existed in various forms for over 15 years. Much of the original documentation from early versions of the AgilePoint product still exists in some form in the currently published documentation — especially in troubleshooting articles and server-side documentation that describe the core technology for AgilePoint NX. As the company has grown and standards have evolved, we have provided more and more information in each documentation topic over time. However, much of the older, less detailed Documentation still exists. As we update these sections of the documentation, we bring them up to the current standards whenever possible.
- Newer functionality may lack some detail or be missing from the documentation. This is because the documentation schedule necessarily lags behind software development somewhat.
Why do many documentation links open in a new tab?
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 Documentationand 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.
Why does the AgilePoint documentation sound formal or unnatural to U.S. English speakers?
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.
How do I provide feedback on the documentation?
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 firstname.lastname@example.org. Documentation feedback does not count against your contracted number of support tickets.