What this page is NOT!
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 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.
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.
Current Version
| Project | Architecture Navigator |
|---|---|
| Release Name | dn |
| Release Version | 3.0 |
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:
- Functionality
- Maintenance
- Infrastructure requirement
| ArchNav | Read The Docs | |
|---|---|---|
| FEATURES | Supported(Y/N) | Supported(Y/N) |
| Web-based | Y | Y |
| Stand alone | Y | N |
| Dynamic webpages | Y | N |
| browser compatibility | N - Works best on Mozilla Firefox | Y |
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 layer | |
| Content is dynamically loaded as the user navigates to new pages. | |
| Offers quick access to documentation in a click. | Documentation is scattered and does not offer a straightforward way of looking up information. |
| Have embedded backlinks to the wiki. | Holds complete and formal technical documentation. |
| Clickable maps in the form of images. | Clickable maps in the form of an SVG diagram. |
| Dynamic code generation | |
| Allow toggling on and off for some features on demand |
INFRASTRUCTURE REQUIREMENTS
| ArchNav | Read The Docs | |
|---|---|---|
| Operating System | GNU/Linux | |
| Web-server | Apache | |
| vCPU Cores | 2 | |
| Memory | 8 Gb | |
| Storage | 1 Gb |
MAINTENANCE
| ArchNav | Read The Docs |
|---|---|
| Requires user training on how to use the tool | Straight forward |
| Will require a team of technical code contributors/committers | |
| Require manual update of the links to point to the current documentation | |
| Has too many moving parts |
FINDINGS
ArchNav brings complexity when designing a clickable image for the Architecture Nav, the process is a tedious one since you'll have to take a snapshot of the existing diagrams bitmaps, convert it to a PNG file, draw shapes around objects on the image to generate coordinates and lastly store the image attributes in a JSON object. This is time-consuming compared to creating OVERLAYS using SVG diagrams.
ArchNav code is not a storage hog since most of it is generated dynamically on demand using PHP and Javascript.
Documentation residing in the read the docs is always up to date and the most current. The Arch Nav will require a manual update of the links pointing to the documentation when there is an update making it a repetitive and tedious task.