...
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 as a Framework
ArchNav is an architectural platform that provides common access to the wiki and RTD. It uses existing ONAP projects diagrams and overlays them with clickable area maps. Its usefuleness has been demonstrated beyond ONAP
-archnav usefulness has been demonstrated beyond ONAP documentation needs
...
| 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 interactive overlay | Links embeded embedded in the image. |
| Content is dynamically loaded as the user navigates to new pages. | Content not dynamically created |
| Offers quick access to documentation in a click. | 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 image 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 |
...
| 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 inkscapeInkscape. |
| Require manual update of the links to point to the current documentation | TBD - 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 ongoing 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, 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 have less versatility than ArchNav has demonstrated.
...
>capture need for infra' maintenance → budget ramification beyond this eval,
RECOMMENDATION
- facade design approach.Implement a FACADE design pattern
As is, the tool can be supported by people with the right technical skill setskillset, however, to broaden the scope and make it accomodating for contribution from technical and non-technical members of the community, a graphical approach would be ideal,,,,
- investigate github webhooks.
...
simple web page with input forms as an interface that is mapped to the JSON object instances. In essence, this will eliminate the need for directly modifying the backend code to make changes.
- Implement webhooks on GitHub with the wiki configuration.
To address the concerns for maintaining an up-to-date documentation reference, exploring and experimenting with some automation methods would be ideal. In this case, webhooks can be configured on github to be triggered to make an update to the flat file storage such as when there is a new release or a release tag changes.