...
| Info | ||
|---|---|---|
| ||
This page has been set up by Nicholas Karimi, ArchNav mentee to document his experiences and understanding of the project as he interacts with it. Therefore, consider this not as documentation for the ArchNav tool but a knowledge-sharing repository. |
Problem Statement
Ideally, in In an environment where we had an ideal Wiki and an ideal ReadTheDocs, a small team would be effective in maintaining an up to date documentation, while developers and end-users who want to look up information on documentation would do it effortlessly.
...
The Architecture Navigator seeks to solve this problem by creating a visual presentation layer with clickable objects representing each individual project under ONAP. The tool aims to offer an interactive interface where users would need to hover over different objects mapping links to the project documentation.
Use Case
The specific use case being addressed by this evaluation is that of providing a method for imaged based navigation to the correct formal doc set.
What is Architecture Navigator?
...
The Architecture Navigator does not create documentation but allows users to easily navigate through documentation that resides in the Read The Docs.
- Describe framework
-archnav usefulness has been demonstrated beyond ONAP documentation needs
-highly versatile method for image based navigation beyond ONAP doc'
Current Version
| Project | Architecture Navigator |
|---|---|
| Release Name | dn |
| Release Version | 3.0 |
...
| ArchNav | Read The Docs | |||
|---|---|---|---|---|
| FEATURES | Supported(Y/N) | Supported(Y/N) | ||
| Web-based | Y | Y | ||
| Stand alone | Y | N | ||
| Dynamic webpages | Y | NSoftware Model | standalone server | SaaS |
| page creation | dynamic | static | ||
| browser compatibility | N - Works best on Mozilla Firefox | Y-browser-independent |
FUNCTIONALITIES
| Architecture Navigator | Read The Docs |
|---|---|
Technologies used include:
| Technologies used;
|
| Works on the browser | Works on the browser |
| Does not create documentation | Creates documentation |
| Offers interractive presentation layerinteractive overlay | Links embeded in the image. |
| Content is dynamically loaded as the user navigates to new pages. | Content not dynamically created |
| Documentation is scattered and does not offer a straightforward way of looking up information. | |
References links to both formal and development wiki | Holds complete and formal technical documentation. |
| Clickable maps in the form of imagesimage overlay. | Clickable maps in the form of an SVG diagram. |
| Dynamic code generation | N/A |
| Allow toggling on and off for some features on demand | N/A |
| Image creation from any source (bitmap image) | Requires image editing/modification |
INFRASTRUCTURE REQUIREMENTS
| ArchNav | Read The Docs | |
|---|---|---|
| Operating System | GNU/Linux | SaaS |
| Web-server | Apache | |
| vCPU Cores | 2 | |
| Memory | 8 Gb | |
| Storage | 1 Gb |
...
| ArchNav | Read The Docs |
|---|---|
| Requires brief end user training on how to use the tool | Straight forward |
| Will require a team of technical code contributors/committers | Requires knowledge of rst syntax and inkscape. |
| Require manual update of the links to point to the current documentation | Has too many moving partsTBD - confirm whether automatic sync with git |
| Has multiple moving parts | Fewer moving parts |
| New features coded by the ONAP community | New features coded by RTD community |
| Initial setup of new infrastructure and on-going support | SaaS |
FINDINGS
ArchNav is a highly versatile platform that supports a wide variety of use cases. However it brings complexity when designing a clickable image for the Architecture Nav, the The process is a tedious one since you'll have to take a requires taking a snapshot of the an existing diagrams bitmapsimage, convert converting it to a PNG file (if not already a PNG), using an external tool to draw shapes around objects on in the image to generate the needed coordinates and lastly to store the image coordinate attributes in a JSON object. This is has the potential to be more time-consuming and error prone when compared to creating OVERLAYS using an SVG editor to create diagrams with embedded links. SVGs with embedded links however has less versatility than ArchNav has demonstrated.
As a platform ArchNav code is not a resource or storage hog since most of it is its file are generated dynamically on demand using PHP and Javascript and none of the items linked from an image reside locally.
Documentation residing in the read the docs is always up to date and the most current. The Arch Nav ArchNav will require a separate manual update of the links pointing to the documentation when there is an update making it a repetitive and tedious task.in addition to the current RTD updates whenever there is a new release of ONAP.
RECOMMENDATION
- facade design approach.
As is the tool can be supported by people with the right technical skill set, however, to broaden the scope and make it accomodating for controbution from technical and non-technical members of the community, a graphical approach would be ideal,,,,
- investigate github webhooks.
For the ONAP documentation use case Nicholas Karimi is going to finish the rest of this paragraph. 