Open jpwhitemn opened 1 year ago
Next steps:
Nice job @jpwhitemn I think another next step is to create a project board containing the work break-down to get this completed. Draft cards are good enough for now and then convert to issues when ready.
The hard part is how we do this in one release cycle. IMO, we should start with just the restructuring of existing content into what you have described above. Then work on cleaning up the existing content as mush as possible before Napa LTS release.
Since Snap suppot is removed with Napa, we should also be removing the documentation as well. https://docs.edgexfoundry.org/3.1/getting-started/Ch-GettingStartedSnapUsers/
@bnevis-i , when I go to https://docs.edgexfoundry.org/3.1/getting-started/ the Snap documentation is no longer in the menu. Also the document your link references is not longer in the repo at: https://github.com/edgexfoundry/edgex-docs/tree/napa/docs_src/getting-started
Please verify that when you navigate to https://docs.edgexfoundry.org/3.1/getting-started/ the Snap doc is gone. THX!
Ok. This is wierd.
If I start at https://docs.edgexfoundry.org/3.0/getting-started/Ch-GettingStartedSnapUsers/ I see it in the index. If I then change the version drop down to 3.1, it sends me to https://docs.edgexfoundry.org/3.1/getting-started/Ch-GettingStartedSnapUsers/ which actually does have the page.
I guess a prerendered version of the page is at https://github.com/edgexfoundry/edgex-docs/blob/gh-pages/3.1/getting-started/Ch-GettingStartedSnapUsers/index.html, but not getting replaced since we removed the source.
Yep, and if you instead switch to 3.2 Odessa, you get the expected Not Found
.
I will kick-off a rebuild of Napa to see if that cleans it up.
đź“š Docs or Wiki Bug Report
This issue supersedes #1141
Per the Napa Release planning meeting, it was discussed and approved for incorporation into the next release to refactor and greatly improve the documentation. Specifically, there was agreement for “significant doc updates”.
@ejlee3 has provided some input to this task with issue #1146.
This topic was discussed in the Jun 21, 2023 architect’s meeting and feedback from that meeting is provided/annotated in the information below.
Having reviewed the documentation and all issues in the edgex-docs repository, the following concrete items are recommended to the community for comment, refinement and ultimately developer/writer actions for the upcoming 3.1 release:
Overall Organization
The top bar sections (Introduction, Getting Started, Security, …) seems haphazard and not helpful to adopters getting to the general category of information they need. Could we provide a more complete, detailed, side menu bar to layout the entire documentation structure for the user? Then use a tile approach on the main page to provide quick clicks into areas of the documentation? This approach is used by projects like Kubernetes, Grafana, or TensorFlow? The tiles take you to important topics directly in the side bar menu and could even someday be selected based on usage statistics.
The side bar menu would be organized per below (highlighted areas are main page tiles). It would be more detailed and contain duplicate references to topics that are common in multiple categories (for example, configuration information would be available through both the service category as well as configuration category). This should be accomplished with duplicate menu items but without duplication of content (i.e. link to the same content from different menu options). Major bullets being the displayed topics with the sub bullets being expanded menu selections.
Note: per the architect’s meeting, there is a desire to keep the menu bar across the top, but the menu bar would contain “bigger” items (but there is not clarity as to what would be in the menu bar).
Note: from the architect’s meeting it was noted that the tiles would largely be the important “getting started guides” and “deployment guides” are things needed first. Eventually, the tiles may be populated dynamically based on doc site stats (unsure how that would be accomplished).
Reorganization/Standardization of documentation Sections
Each section of the microservice documentation sections is organized and written as it came from different authors with different objectives and considerations. This is, in actually, a point of fact versus criticism, but it also makes it difficult for adopters to negotiate the documentation and find the information they need. The entire documentation set should be overhauled such that each of the related sections should have the same categories of information and structure. Also, the micro services sections contained a lot of information (a hodge podge of model info, tutorials, configuration, etc) that made finding the needed information hard. This section should be greatly simplified to provide some general guidance on what the service does and then pointers out to api and configuration guides, and pointers to tutorials for the service. A small section (Details) can provide service specific detailed information (where there is no other place to put it).
The following structure is suggested for each service section (using core and core data as an example):
Increased Focus on Getting Started Guides
Getting started guides need to focus on the most fundamental and critical needs of the platform (install run, get stuff connected, check that its working) in small, easily digestible guides. A final guide should help walk an adopter through the entire platform at a high level
Increased Focus on Practical Examples/Tutorials
We need more step-by-step guides on some of the most common needs in the system, probably organized by category. Below is a set of known tutorial needs
Considerations, Open Questions, and Research Needed
Relevant edgex-docs issue input
1106 – stale images
1037, #1103 – get rid of 404s, broken links and provide a better page for reporting broken links
28, #195, #855 – improve documentation around how to use the device services SDK, device profiles, and API documents around the same
714 – move to a better image tool
642 – better documentation/examples on cloud exports
21, #121, #489 – better documentation on using binary data/CBOR data
33 – better documentation on how to create new app services and docker images for those