HTML-report layout for knowledge-base documentation and comments

[evlibra]

In order to adopt HTML-reports for knowledge-base documentation suitable for comments, below are proposals of layout improvements. As basis were taken built-in HTML-report combined with single-page-html-report. I know that is too much at this request. Please advise on technical limitations, implementation ideas, or other layout adjustment suggestions.

1. Devote whole left-panel to tree

• Views at the top,
• Elements at bottom (some might be hidden).*
• Remove Documentaion window under the tree
• Keep the tree unfolded (or may be just views) The idea is to use it like a table of contents for ease of navigating through (view/elements) pages

2, 3) Show only Documentation tab (below diagram), which will also include documentation of elements depending on selection Under the Tab:

• hide Type column,
• add Documentation column
• remove relationships (it is already at a tree), *or place it at right panel bottom Type can be used for filtering what documentation to show. The idea is to bring more focus to documentation as a knowledge base

4. Select an element in the model tree or in a view to show its details at Documentation tab

• If no element selected - show details of View. 4.1) Would it be possible to highlight the selected element on the diagram?

5. Allow Zoom to down-scale even more - for larger documentation area, if required?

6. Enable hypotes.is as plugin for inline-comments (annotations & highlights)

[Phillipus]

Hi, will you be implementing these proposals or are you asking that we implement them?

[evlibra]

Hi, will you be implementing these proposals or are you asking that we implement them?

Hi @Phillipus,

It depends. If it can be done in the next couple of months I'll be more than happy. I needed it long back and now am committed to moving it forward with a desire to contribute (because it might facilitate my other open learning community initiative).

Having not much experience with js and HTML, I could initiate the updates in a fork, and someone can review. If I'll be stuck at some point, I'll ask for help. For (1) and (6) I already have some drafts, and (2-4) might need more research/experience. Since you might already have or planned similar updates, it would be good to coordinate between us.

What would you say?

[Phillipus]

Please go ahead. This is not something that I have planned to implement. (I have enough to do already. 😄 )

[evlibra]

Got some initial results https://evlibra.github.io/archi-body/?view=c14cadeb-c7f3-462e-aa9d-1a3e66872563 Implemented 6, 1 (partially), instead of 2,3 - got an idea to show element at the center, and model - at east. Commit 11d1b84 Initially did that to avoid nested iframes, but now see it might be not so bad. Still learning, already got some challenges - will list them later.

[evlibra]

Still learning, already got some challenges - will list them later. Challenge 1 - if starting form the hypotes.is comments page https://hypothes.is/groups/3o59xLKk/cbt, the page of individual element is open, without seeing its context in model: https://evlibra.github.io/archi-body/198667f9-f68d-46a1-8bf6-01c97c861d17/elements/id-32c37e8df7f546efaecd7aab152a83b6.html#annotations:5tqalo_eEe2_31tIRXHQ6w Idea of the solution might be to include link on its view at each element's page, e.g. at the bottom.

[startsevsa]

You can hide tree elements (folders and elements), by using the property "hide_from_export" and setting it to true. I use this option for all top folders, except "views" - because

• the is no need for them in HTML (without analysis and visualiser tabs)
• the knowledge base (or architectural repository, as it's usually called) main purpose is to provide views for the wide audience

[evlibra]

hide_from_export

@startsevsa , sorry for the naive question, but in which file are you setting the hide_from_export property to true? In modelreport.stg ?

[evlibra]

@Phillipus What is the best place in code to catch the mouse clicks (e.g. to highlight clicked element)?