edgexfoundry / edgexfoundry/edgex-docs

Refactor Documentation for better UX

Open
#1,146 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
HTML
Stars
44
Forks
88
PR merge metrics
No merged PRs in 30d

Description

# 🚀 Feature Request

### Relevant Package [**REQUIRED**]

This feature request is for...
all the docs!

### Description [**REQUIRED**]
A clear and concise description of the problem or missing capability...

- re-read and potentially (if resources allow) do UX tests on the getting started instructions - is this something we want to keep up to date? (old references to past releases, previous go versions, and previous docker versions
- improve security section
- improve overarching style - do we want any instructions numbered? should we avoid the use of long paragraphs in the instructions? how can this be more user friendly - [these steps](https://docs.edgexfoundry.org/3.0/security/Ch-Configuring-Add-On-Services/) and [these steps](https://docs.edgexfoundry.org/3.0/security/Ch-RemoteDeviceServices/) required multiple read-throughs before the instructions were semi-clear
- improve the organization of each chapter - many chapters - like security, examples and tutorials to name a couple, seem to have pages in a random order - is there a way to group pages or better organize things so that users get a better sense of what information is present?

### Describe the solution you'd like
If you have a solution in mind, please describe it.
- determine a way to group information or present it better
- determine a consistent way to organize the documentation
- focus on usability and readability - both of which aren't the easiest if unfamiliar with the project

**Things that are hard to find:**
- it is hard to find information on the different targets or option with compose builder - is this documented anywhere? or is that up to the developers to figure out?
- it's pretty hard to find configuration information and appropriate values - if you don't know what you are looking for, it is nearly impossible to find without looking instead at the source code
- what are all the different compose-builder options- is there a list anywhere - how can users leverage this tool to help them build images for securing services or using services in a non-secure way.

### Describe alternatives you've considered
Have you considered any alternative solutions or workarounds?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.