Inline comments would be a fantastic feature

[evlibra]

for example like this https://tsi.github.io/inlineDisqussions/ Comments e.g. on documentation would allow getting user feedback on published models, like this https://evlibra.github.io/Archi_Body/ https://evlibra.github.io/Archi_Body/198667f9-f68d-46a1-8bf6-01c97c861d17/views/b90805b2-7a2c-47e2-86a7-b2d5d1dd95a6.html or this https://evlibra.github.io/Archi_ASPICE/ https://evlibra.github.io/Archi_ASPICE/id-322369a4-b2ad-4c96-8d58-a5d264295809/views/b4a58a17-a562-4304-b735-3b37cc0d68d2.html

[jbsarrodie]

Hi, I'm sorry, but "XXX would be a fantastic feature" is not (at all) a feature proposal. Instead of simply throwing links to external resources, could you please elaborate on your idea, explain what use-case it adresses, how it could manifest in Archi, who are the target users... ? Without such detailed explanation I'm afraid I'll have to close this issue (and maybe miss a fantastic feature)

[evlibra]

Hi, my apologize for making the initial post in a hurry.

The idea is to let the model evolve based on target users feedback. In most use-case, target users would be non-technical or, at least, non-architects e.g. trainers, patients, managers, etc.

If users have questions/feedback to any part of the model or documentation, they should be able to provide their comments within the related part/text directly (inline). They should be able to highlight the element or text and add the comment that refers directly to that. Based on feedback, the architect will adjust the documentation/elements in Archi. Manifestation to the Archi could be e.g. by utilizing the element properties.

One of the options could be to "tweak" published HTML-reports (as on examples above) by adding inline comments (at least to documentation text).

Second option could be to utilize review comments on git-hub content of the model, as published from Collaboration plugin. But it may have limitation of making the model user-friendly and highly accessible by the end-users to view/navigate (ideally, without the need of installing the tool) - as in case with HTML-report.

But it looks like both options are not having direct impact on the Archi. So, probably just using CSV-export shared as Google Sheets, could be most simple work-around to gather/track the feedback on element's description, which would lack the user-friendliness and graphical view of the model.

So far I was trying to find 3rd party tool for publishing Archi models for end-users with feedback on it, but no one suitable exists yet. Another limitation became custom icons (3rd party unable to render it, as relay on open exchange format). That is why I came back here with request of native support of feedback on models, ideally, in the format of inline-comments (which may be part of model or external linked to model's elements by its IDs).

[jbsarrodie]

Hi,

Thank you for this more detailed explanation. I do agree that this kind of feature would be good because they would allow feedback. I did it with Jira issue collector and though about GitHUb/GitLab issue and also Disqus. The issue is that there is no way to do this without a third party solution (whatever it is), thus it's up to users to setup their own solution. I really would like to find a good and simple solution for adding such comments, but for the moment I didn't find one.

FWIW, you can easily customize the builtin HTML export (it is based on StringTemplate).

Re "inlineDisqussions", the major drawback I see is that it rely on paragraph numbering, so if you remove or insert a paragraph, then comments are no longer at the right position and history is lost.

[evlibra]

I have tried to apply "inlineDisqussions" - managed to make connection with Disqus (for Archi_Body). The issue is that structure of builtin HTML export seems to be not suitable for "inlineDisqussions" - yet at I was unable to find suitable tag to pass to jQuery. The customization of builtin HTML export seems not so easy for me, or at least I would need some hint where to start from with some samples (e.g. shall I fork and play with reports/html/HTMLReportExporter.java , or create plugin like singlePageHTML? ). For inline-comments the report would better be more plane - with less panels - just image and list of elements beneath it (and somewhere - description on clicks).

Re "inlineDisqussions", the major drawback I see is that it rely on paragraph numbering, so if you remove or insert a paragraph, then comments are no longer at the right position and history is lost.

Can think of using data-disqus-identifier = "element id", so the report could just write it for each element.

[jbsarrodie]

The issue is that structure of builtin HTML export seems to be not suitable for "inlineDisqussions" - yet at I was unable to find suitable tag to pass to jQuery.

The whole documentation is included in a div tag which is a direct child of another div tag with id="documentation", so you should be able to access it through the following selector: #documentation > div

This means that inlineDisqussions will be attached to the whole documentation block, not to each paragraphs (because there is none)

The customization of builtin HTML export seems not so easy for me, or at least I would need some hint where to start from with some samples

Hacking the report involves:

• Adding your static resources (css, js...) into Archi/plugins/com.archimatetool.reports_x.y.z/templates/html matching subfolders
• Updating Archi/plugins/com.archimatetool.reports_x.y.z/templates/st/frame.stg, especially the frame(element, map) function which starts at line 128 and is in charge of the rendering of all views and elements's pages. As you want these comments to be enabled everywhere, then the easiest way to do it is to simply add a <script> section before the end of head (line 146).

shall I fork and play with reports/html/HTMLReportExporter.java

No need for that, everything should be done in the template.

or create plugin like singlePageHTML?

That's another option. You'll then have more freedom, but you'll have to maintain the whole thing yourself.

For inline-comments the report would better be more plane - with less panels - just image and list of elements beneath it (and somewhere - description on clicks).

Another option would be to simply add a tab in which the comments are shown

Can think of using data-disqus-identifier = "element id", so the report could just write it for each element.

This won't work. This would have to rely on internal id for documentation's paragraphs, but this doesn't exist in Archi, so there's no way to identify a specific paragraph at all.

BTW, there are other (and maybe best) solutions to manage comments for static content (which is our use-case here). A quick search shows that these two solutions seems interresting:

• Utterances
• Staticman

[evlibra]

I did more research and it looks like universal commenting is challenging for many years in the whole web world. Even web-browser commenting extensions could be considered (if 3rd party shall be dealt with anyway):

• Epiverse
• Dissenter
• hypothes.is

But looks like with this we're risking to step into hacker's world, as comments are "golden rush" not only from technical point of view but many others.

[Update]: hypotesis.is works pretty well (with nice highlights and comments in its own tabs), on the list tree (and not on the documentation or other elements like diagram - so, most probably, would restructure report to more simple and plain view with the list tree unfolded, as mentioned above). [Update 2] To use it on mobile or without installing a browser plugin, this kind of links can be used (just put https://via.hypothes.is/ before your link): https://via.hypothes.is/https://evlibra.github.io/archi_body/

[jbsarrodie]

hypotesis.is works pretty well

Interresting, I'll try it. This might be a good candidate for models which are shared with everyone (i.e. which contains no confidential information).

In the meantime I've discovered Vssue.js which is a very interresting commenting system backed by a git server and supports the most commons (GitHub, GitLab, BitBucket...). This makes it the ideal candidate for confidential content in an enterprise setup (as most of the time people will host their model using coArchi and git).

[jbsarrodie]

[Update 2] To use it on mobile or without installing a browser plugin, this kink of links can be sued (just put https://via.hypothes.is/ before your link): https://via.hypothes.is/https://evlibra.github.io/Archi_Body/

There' also a bookmarklet

[evlibra]

Hacking the report involves:

• Adding your static resources (css, js...) into Archi/plugins/com.archimatetool.reports_x.y.z/templates/html matching subfolders
• Updating Archi/plugins/com.archimatetool.reports_x.y.z/templates/st/frame.stg, especially the frame(element, map) function which starts at line 128 and is in charge of the rendering of all views and elements's pages. As you want these comments to be enabled everywhere, then the easiest way to do it is to simply add a <script> section before the end of head (line 146).

Will hacking reports require building binaries of plugin? Or can be done just twicking at resulting report (css, js.. are there, but no st - so I have manually added scripts at resulting html). Since comments seems to work with hypothes.is, I need just make as much content of the report commendable as possible e.g. see unfolded the whole tree with links to all elements. The simplest seems to be md-doc script from rich-biker, but I want to have the diagrams clickable.

[jbsarrodie]

Will hacking reports require building binaries of plugin? Or can be done just twicking at resulting report

It only requires to change the .st files of your Archi installation, no need to comping Archi again. Simply change those files in your Archi setup and that's it: all reports you'll create will be updated.

The simplest seems to be md-doc script from rich-biker, but I want to have the diagrams clickable.

I've created a script to create a single page HTML export. Diagrams are not clickable for the moment but that's on my roadmap. At some point in time this could become the new standard report for Archi.

[evlibra]

Thanks for the response @jbsarrodie - I can see now that you've meant Archi installation folders - will try tuning it for a more comment-friendly layout. Probably. I may need to refer to Stringstemplate doc - / Templates section or refresh HTML skills. Priority (1) is to make the tree not collapsed by default for folders at ui-layout-west ui-layout-pane In order to see a better overview of what was commented at a high-level - kind of "table of contents" / "terms definitions" The next priority (2) will be to decide how to handle comments of separate related pages (shown at the panel from image-map clicks) - maybe make them open as modal dialogs (or at new windows) by default.

Regarding the single-page HTML export - I've tried it as well here, that is a great idea in general (especially for the use-case of publishing on corporate portals - Sharepoint, Confluence, etc), but for the current use-case that cant be of value yet - without the feature of the clickable image and view-navigation (kind-of drill-down but to views from a view-reference placed at the element of current view), and need to decide where better to keep the description of the elements (e.g. where to show it on clicks)

[Update] (1) was pretty simple - just changed setup model tree from .hide() to .show () at row 46 of model.js (maybe think of selective hide), (2) looks more challenging though.

[evlibra]

I'm stuck - how to sort elements in model tree without click - after I've made them show() by default (at row 46 of model.js)

[evlibra]

Got 2nd issue (comments for elements description at iframe) resolved - by enabling annotation of iframed content, as advised here: https://h.readthedocs.io/projects/client/en/latest/publishers/embedding/#enabling-annotation-of-iframed-content :)

[evlibra]

Maybe that is a crazy idea, but we could think of integration with online boards e.g. miro: https://miro.com/api/ for online commenting of certain views.

[jbsarrodie]

Maybe that is a crazy idea

Yes ;-)

Seriously, not sure of the use case (MIro is not really meant to be a comment system)

[evlibra]

Happy New Year! I did some research, and see good potential in interoperability with kumu.io as publishing platform. Straight forward it is achievable using export to Excell. Except of built-in comments (in pro version) kumu.io has Disqus plugin. One problem is that images cant be exported, but potentially it can be done through properties (as I remember, Archi cant render image from url, even in version 4.9?).

[evlibra]

This topic can be closed due to dependency on HTML-report which has to be improved to be compatible with Hypotesis.is.

With the thought to keep Archi focused on its main purpose - model (EA), naturally integrating with the other open-source solution which is specializes on comments as "A conversation layer over the entire web that works everywhere, without needing implementation by any underlying site."

There are several threads related to the HTML-report, but I'll try to summarize requirements for HTML-report - "to enable a conversation over the world’s knowledge". And hopefully will try to support it with best of my skills. [Update] Created separate issue with ideas for HTML-report layout adaptation: https://github.com/archimatetool/archi/issues/892

[evlibra]

• Epiverse
• Dissenter
• hypothes.is

++ Readwise and Liner, but looks complicated and $$, hypothes.is looks simpler and open-source