| Info | ||
|---|---|---|
| ||
This page has been set up and created by Nicholas Karimi, ArchNav mentee ( Profile ) 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. |
...
- link to current source code: https://github.com/ca2853/onapdocs/tree/dev
How does ArchNav Work?
- ToDo Nicholas Karimi complete evaluation by
Side by side comparison between ArchNav and Read The Docs
...
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.
- >capture need for infra' maintenance → budget ramification beyond this eval,
Moving ArchNav out of the lab to production will have a significant cost implication to the Linux Foundation Networking. The application will require to be run on cloud server instance with resource requirements as oultlined on the (Infrastructure requirements) section above.
RECOMMENDATION
- Implement a FACADE design pattern
...
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 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.
Recommendation based on the Use Case
Based on the above findings, the ArchNav platform has to a large extent solved the highlighted shared problem on the problem statement. The goal for any software program is to eliminate complexity and not introduce one. Architecture Navigator on one side which is, offering intuitive graphical navigation, and quick access to the documentation, has consistently produced stellar performance. Conversely, the platform which is a stand-alone application fails in providing an integration structure for providing a single entry point for the ONAP documentation. Additionally, a pain point to be of concern would be the complexity that might arise in implementing clickable image features.
That said, to eliminate any confusion that could arise when ONAP community members try to access the official documentation, ArchNav as a parallel option would not be the ideal solution. However, the functionalities of the ArchNav can be more useful to the opensource community as an alternative to quick navigation and access to formal and development project information. Case in point, the ArchNav platform would be an ideal entry point for the development wiki where developers seeking to navigate the unstructured wiki would be presented with an interactive image-based layer that directs them to the projects development wiki in a single click. To facilitate something like this it would really be best to have ArchNav as an open-source project with the appropriate governance applied to attract the appropriate maintainers and contributors.
Ultimately any documentation model should fit seamlessly into the existing support model and infrastructure for the documentation itself. As such managing, all of the content in the documentation repo in a form that does not require a programming background seems most appropriate to ensure maintainability.
Conclusion
The point here was to highlight the functionality and features that the two tools offer to the end-user. With an objective for providing quick navigation to the documentation based on visual presentation, it would be ideal to have the image-based navigation implemented within the official documentation. Having the application of image navigation within the documentation will ensure that the entry point to the official documentation remains unchanged hence providing a consistent and improved user experience unlike having community members access the documentation through a third-party application. This despite solving the commonly shared problem which is the lack of a simple and intuitive way for accessing the documentation, would bring more confusion of duplicity. For the use case in the original problem statement, ArchNav is probably not the correct solution. However, it may be an entirely appropriate solution to use ArchNav as a visual entry point to areas where information is less structured than our formal documentation set or we do not have full control or management over the source of the documentation being sought.