Proposition: split the documentation by user profile

[minijackson]

Something that has been on my mind for a while, is that as a system administrator / package creator, I have to jump to a lot of different places in Phoebus' documentation:

• Preference listing is my number one consulted pages, but it's in "Developer documentation", despite me not being a developer, so I always miss it
• Locations, and Change Log, also in the "Developer documentation"
• The various services documentation, in "User documentation"
• Sometimes the applications documentation
  • While they often are for operators or UI designers, sometimes they document preference settings

The proposition

My proposition would be to create 4 or 5 sections, by user profile.
This hopefully would make the documentation more user-centric, by:

• concentrating related documentation, reducing how much a user would have to "jump" to articles that are "far away"
• making documentation pages focus on one type of user, avoiding having pages that contain too much content
  • for example, this would avoid articles that explain all of this at once:
    • how to use an application (operator documentation),
    • how to add a widget for it (display designer documentation),
    • how to configure it (sysadmin documentation),
    • and how it's implemented (contributor documentation)
  • these kind of articles would be split and put into several sections, which hopefully would make them less confusing

Sections

Here are the different profiles / sections:

1. Operator
   • A user which uses Phoebus mainly for viewing display, and using applications
   • This section would focus on:
     • starting Phoebus
     • using menus
     • opening and interacting with displays and applications
     • etc.
   • This would contain most of the current "applications" documentation
2. Display designer
   • A user which designs displays
   • This section would focus on:
     • listing the different types of widgets
     • what their properties are
     • how they interact with applications
     • the syntax for writing PVs of different datasources
     • the simulated PVs syntax
     • etc.
3. Control system developer (to be confirmed)
   • An EPICS IOC developer, MQTT developer, or any developer that develop an "IOC" which will be visualized with Phoebus
   • In other words, a developer for a Phoebus datasource
   • This section would focus on:
     • How to write an IOC or equivalent, so that it integrates well with Phoebus
     • How EPICS fields are used in Phoebus (or equivalent for other datasources)
4. System administrator
   • A user which packages / deploys Phoebus
   • This section would focus on:
     • How to build Phoebus and the various Phoebus services
     • How to configure and deploy the Phoebus client:
       • Settings file locations
       • The available settings / color.def / font.def
     • How to configure and deploy Phoebus services
       • Including how those services integrate with external software (Kafka, ES, etc.)
     • How to use the various Docker containers
5. Phoebus contributor
   • That's you!
   • This section would focus on:
     • The architecture of the source code, Java classes, etc.
     • How to develop using Eclipse, etc.
     • The process of contributing
     • How to make a new Phoebus release

On my laptop I have a rough draft of which current article would go where, but I would like your input before create a pull request.

Diátaxis

I think it might also be a good time to follow the Diátaxis model, where each section would be split into for article categories:

• Tutorials: for onboarding new users
• Guides: for showing how to do specific things
• References: for complete lists of preference settings, simulated pvs functions, javadoc, etc.
• Explanations: to explain concepts