edgexfoundry / edgex-docs

42 stars 85 forks source link

Refactor / Overhaul Docs for 3.1 #1151

Open jpwhitemn opened 1 year ago

jpwhitemn commented 1 year ago

đź“š 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

jpwhitemn commented 1 year ago

Next steps:

  1. do some prototyping with mkdocs to test the art of the possible of some of these demands (especially around mkdocs new version)
  2. identify open source documentation that the community thinks serves as a good template
lenny-goodell commented 1 year ago

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.

bnevis-i commented 11 months ago

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/

lenny-goodell commented 11 months ago

@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!

bnevis-i commented 11 months ago

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.

lenny-goodell commented 11 months ago

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.