[
https://issues.apache.org/jira/browse/NIFI-667?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14588165#comment-14588165
]
Robert J. Mills commented on NIFI-667:
--------------------------------------
The thinking was more general. At the moment, extension providers have no
extension mechanism for high-level/summary documentation within NiFi
(notwithstanding the detailed documentation mechanism for individual
extensions.) As an example, imagine a healthcare focused extension provider
who authors ~100 healthcare focused extensions that in their entirety represent
a major extension to NiFi. Other than their own web site, what mechanism is
available (to the extension provider) to embed an overview/summary of their
extension "package" (tar, zip, etc...)? Moreover, if the healthcare provider
versions their "package", what mechanism is available to identify the package
version within NiFi? If the installation instructions for the package are 1.
Decompress the package, and 2. Put the contents (nar bundles) into the lib
directory of your NiFi installation, then there is no way for the NiFi
framework to acquire the package (tar, zip, etc...) version in order to provide
it in the NiFi UI. However, if the extension provider can extend the NiFi
embedded documentation set with their own document(s), then there is an
opportunity for them to included a package version within the extended
documentation.
With respect to nar level documentation, my initial reaction is, "Why should
the average NiFi user have to know about or deal with nars? Does the average
user of a Java based application have to know which jars are deployed within
their application?" But on second thought, in a marketplace (where nars are
the deployable unit for extensions), perhaps there are use cases for being able
to provide nar level documentation. While a marketplace should primarily be
business/mission/task focused, it is inescapable that once a user has selected
an extension (from the marketplace), their choice will have to be mapped to a
deployment artifact (a nar). Moreover, from a troubleshooting point of view,
admins are going to need to get nar version information from users (see
NIFI-666). Consequently, exposing the idea of nars (to users) may be
inescapable.
If NiFi were to support nar level documentation and support the ability to
extend the high level documentation, along with the current component focused
documentation, then an extension provider would have the ability to add
documentation at three different levels of detail. Hopefully, that would cover
98% of the available use cases.
> Provide ability for an extension provider to augment the standard NiFi built
> in documentation with their own "document(s)" and have the augmented
> documents available in the help/NiFi Documentation "window".
> --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
>
> Key: NIFI-667
> URL: https://issues.apache.org/jira/browse/NIFI-667
> Project: Apache NiFi
> Issue Type: New Feature
> Components: Core UI, Documentation & Website, Extensions
> Reporter: Robert J. Mills
> Priority: Minor
>
> The built documentation is quite useful, in that it provides opportunities
> for both
> - High level/tutorial style documentation (Overview, User Guide, Exp Lang
> Guide, Admin Guide, Rest Api, Developer Guide), and
> - Detailed component specific documentation
> The detailed component documentation can be augmented simply by adding a
> component with its associated docs. However, what mechanism is available for
> adding to the list of high level documents?
> What follows is one possible "use case".
> Organizations that create their own custom components may identify the
> components as proprietary, and therefore not releasable to the public.
> While each individual component can be documented in detail (using current
> mechanisms), an organization may wish to provide a high level/tutorial style
> overview of their entire "package"/group of proprietary
> extensions/components, including a version number for the "package".
> Note that the request is not for a mechanism to augment/modify the "standard"
> Apache documents, as they should reflect what is provided by Apache. Rather,
> the request is for the ability to add extension provider documents to the
> list of documents listed in the NiFi Documentation "window"/page.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
