Integrate documentation with syndesis-ui

[jludvice]

Let's take a look on several issues of the same kind.

There are places like this syndesisio/syndesis-ui#529
where is citizen user supposed to put some data in.
He might know the context of Salesforce, but how can he be sure what's the correct format?
Where could he find out more informations?

It's the same here syndesisio/syndesis-ui#572
He could fill date/time data in human friendly syntax. But what that syntax is?
Are there other places where is this syntax supported?

We could probably add some description fields as we go,
but how long it will take until they are out of sync with documentation?
Can we come up with a systematic and maintainable way?

Can we inspire in Jenkins UI for instance? I know it's far from perfect,
but it has one nice feature. Majority of config elements has a Question mark.
As a user I can always get some basic explanation.

Can you imagine situation where we have documentation where

• each section contains some ID and annotation
• we have Angular2 help component which takes ID and pulls appropriate annotation from docs
• appends a http link to full documentation page
  

Wouldn't it be nice and easy to use for user?
What do you think about it @kahboom @rhuss @kcbabo @sjavurek @syndesisio/design-ux ?

[jludvice]

Just saw your issue syndesisio/syndesis-ui#568 @TovaCohen
What do you think about pulling documentation annotations into syndesis ui?

[kcbabo]

In some cases, the input will be governed by a control (e.g. field chooser for the Salesforce unique id field). That said, I definitely agree with your suggestion in principle. Fields that accept free form input should provide some advice on what goes there.

[TovaCohen]

@jludvice , I'm all for pulling documentation annotations from code into the UI. But only if a writer and not an engineer has the final say on the content of the annotations. Engineers can enter initial annotations, but writers would edit or perhaps just approve them. I think there is general agreement that javadoc is written by engineers for engineers. But documentation annotations in Syndesis code would be for citizen integrators. So the documentation annotations require the same attention that we give to typically delivered user documentation.

[jludvice]

@TovaCohen totally agree.

My idea was to use documentation team as a primary source.
Engineering would provide placeholder and content would be pulled from documentation based on some identifier.

Technical implementation is a good question though.
I can imagine the syndesis-ui part -> we would have just angular2 component that accepts identifier and does some (rest?) call to fetch docs content.
Would it be possible to generate some "catalog" / knowledge base as part of asciidoctor build ?

Something that would look like

HTTP GET  http://wherever/HUMAN_FRIENDLY_SYNTAX

{
    "annotation" : "You may use h for yours, m for minuts and s for secons. For instance 3h45m58s would mean time period of  3 hours, 45 minutes and 58 seconds.",
    "url" : "http://syndesis-docs.wherever.com/user_guide/1.0.0.Final/human_friendly_syntax"
}

[TovaCohen]

Hi @jludvice, I don't know anything about using Asciidoc source, or AsciiDoctor, for annotations, but maybe @fbolton does.

[fbolton]

As far as I know, it's not terribly easy to extract strings from Asciidoc content. At least there don't appear to be any ready-made tools for the job. It's probably easier to define the UI strings in a simple format and then consume it in Asciidoc and in the UI.

For example, a simple approach might be to define the UI strings using Asciidoc attributes, for example:

:uistring-1234: This is a UI string.
:uistring-1235: And this is another UI string.

You can then add these strings to Asciidoc content by including the attributes file and substituting {uistring-1234}. The UI tooling could easily consume strings in this simple form. But this is just off the top of my head. This needs a bit more investigation and brainstorming.

[rhuss]

I started some time ago a project https://github.com/rhuss/poblano which as about extracting and generating XML schema and Asciidoc snippets from Java based annotations (in this case for a Maven plugin).

This concept could be easily extended for other code generation context. I agree with @fbolton that its easier for Asciidoc to consume (include) externally created snippets. I would go even so far to create some simple asciidoc documents (e.g. for various possible parameters or other help texts) with proper HTML 'anchors' and then possibly a description language like in @jludvice example above for the UI pick up the links.

[kahboom]

Shouldn't this be in the syndesis-docs repo? Just curious

[jludvice]

I thought that implementation of this feature would span over multiple repos like syndesis-ui, syndesis-docs, maybe something other?? So this looked like best place to me @kahboom.

[fbolton]

In a recent conversation with the "Messaging as a Service" docs team (the EnMasse project), we discovered that they already have a tool for extracting UI labels and tooltips from their Asciidoc documentation. One of the EnMasse developers, Ernie Allen, created a script to extract content from Asciidoc source, producing a JSon file as output:

https://github.com/ErnieAllen/routilities/blob/tooltips/parse.py

And here is a sample of an Asciidoc file that works with this tooltip extractor script:

https://raw.githubusercontent.com/ErnieAllen/routilities/tooltips/model.adoc

WDYT? Is this something we could work with?

[naciao]

+1 for tooltips, and for extracting the content from the Asciidoc source so that we can single-source, reuse and maintain. Thanks for sharing this, @fbolton!

[TovaCohen]

I agree with @naciao -- it would be AWESOME if we could do this!

[rhuss]

I like the idea, sounds good. What I'd imagine, instead of using Python in the build process (which would be tedious to use on the various CI systems we have), what's about creating a simple Maven plugin based on http://asciidoctor.org/docs/asciidoctorj/#reading-the-document-tree which extracts the asciidoc parts and creates the appropriate JSON file which then could be included in the UI for the tooltips ?

Of course, it depends on where the documentation lives and how it is generated (via Maven or directly with the ruby asciidoctor ?) as this is supposed to be the place where the tooltips are generated and then fetched by the syndesis-ui process which is a yarn based build.

I guess the easiest way to share the generated tooltips is via GitHub directly, so that the generated file needs to be checked in, too. The alternative way would it to be shared via a Maven / npm repo.

( @zregvart another data point for a mono repo, where we simply could copy it over ;-) Maybe we should collect all data points in favor for a monorepo ?)

[fbolton]

Using Maven would be ideal. We already use the Maven Asciidoctor plug-in as the toolchain for building upstream docs in the syndesis-documentation repo, so this sounds like a very compatible approach.

[rhuss]

FYI: As mentioned in syndesisio/syndesis-documentation#20 @lburgazzoli will start to work on the mentioned Maven plugin in some days.

[gashcrumb]

Was there a follow on issue created for figuring out how this should be integrated in our workflow?

[rhuss]

No, not yet. But you created one ;-) Thanks for that !

[rhuss]

I keep this open for Sprint 19 until we have the Maven integration.

[kahboom]

This is completed, but not automated. Not sure if that makes this Epic complete, as automating it is an improvement and a separate epic altogether (imho).

[TovaCohen]

I don't know what is required to automate this. @fbolton is looking into this. Can this be worked on in the current sprint? (Sprint 20).