Architecture Navigator Knowledge Transfer

Problem Statement

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.

Currently, the Wiki is not structured. There are two sources for ONAP information, the developer wiki, and the ReadTheDocs. This is a problem because some of the documentation on the wiki is not quickly moved to the ReadThe Docs where essentially it is supposed to reside and gets outdated pretty quick.

This makes it very difficult to find information and find the most current and relevant one. With so much information scattered in the wiki, minimizes value to the users and they will tend to forgo looking up for documentation they were after.

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?

Architecture Navigator is a web-based tool that provides common access to the wiki and the Read The Docs documentation. It uses existing project diagrams and overlays the diagrams with clickable are maps.  A clickable area object within the diagram is a visual representation of the individual ONAP projects which have hyperlinks embedded on them such that, when a user hovers a mouse over the object and clicks, they are redirected to the project documentation or the wiki.

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

Technical Details

• ArchNav does not have any static HTML pages. All HTML pages are dynamically created in real-time based on the "Path" component in the URL request.

The path drives menu creation.

• ArchNav uses a filesystem DB to store all JSON objects.

• Area maps are defined using a common JSON object.
• Developed using PHP, JSON, CSS, JS
• Apache Webserver 

Design Overview

As mentioned in the technical details, ArchNav HTML pages are dynamically created. A JSON object is defined in the notion of topics and sub-topics.

Topic

A topic is defined as a major project such as 5g-blueprint, o-ran e.tc

Sub-topic

Subtopics are components that are necessary to the Topic.

Other Information:

• link to current source code: https://github.com/ca2853/onapdocs/tree/dev

How does ArchNav Work?

• ToDo

Side by side comparison between ArchNav and Read The Docs

This side  by side comparison targets the following areas:

1. Functionality
2. Maintenance
3. Infrastructure requirement

FUNCTIONALITIES

INFRASTRUCTURE REQUIREMENTS

MAINTENANCE

FINDINGS

ArchNav is a highly versatile platform that supports a wide variety of use cases. However it brings complexity when designing a clickable image, The process requires taking a snapshot of an existing image, converting it to a PNG file (if not already a PNG), using an external tool to draw shapes around objects in the image to generate the needed coordinates and lastly to store the coordinate attributes in a JSON object. This 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 is not a resource or storage hog since most of 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 ArchNav will require a separate manual update of the links pointing to the documentation 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.