[doc] Documentation restructure & improvements

[GregAC]

I'm looking at ways to improve the current OT documentation (as seen at https://docs.opentitan.org). Whilst we do have a decent amount of documentation I don't think it's always clear where to look to find information on particular topics if you're not already familiar with the project. I intend to propose some restructuring and identify any gaps where things need writing, improving or updating.

As a first step I wanted to assemble some documentation 'user stories', a brief description of the kinds of people who may be using the documentation and what they're aiming to do. We'll take a look at the current structure with each of these in mind as a way to guide the restructuring.

I've done an initial set below, please edit this to add more (or comment if you don't have edit permissions). Any more detailed feedback or suggestions is also welcome.

User Stories:

• General, new to the project want to understand how to ‘get going’
• General, wanting to setup an OT environment for initial trial/testing purposes (either in sim or FPGA)
• General, wanting to get to grips with what OpenTitan provides with deep dives into topics of interest
• General, wanting to understand the status of the project (e.g. what V1/D1 etc means, which block is in each, status dashboards for regressions/lint/implementation)
• Software engineer, wanting to understand the build process
• Software engineer, implementing software (e.g. DIF/driver) for a new IP block
• Software engineer, writing software using existing libraries/DIFs
• Software engineer, wanting to understand the details of a particular IP block interface and workings
• Software engineer, interested in the software stack (What OT firmware does, how boot process works etc)
• Hardware engineer, wanting to implement a new IP block
• Hardware engineer, wanting to understand how a current IP block works
• Hardware engineer, wanting to understand the topgen/reggen processes
• Verification engineer, wanting to run regressions, both full/CI and specific tests or target specific blocks
• Security researcher, wanting to understand the OT security model

[cdgori]

Not sure if this is useful, but just based on the inbound email questions we seem to get:

• Hardware engineer, wanting to port to their favorite / a different FPGA board target

[dsandrs]

• General, Overview of the product, structured like a data sheet/brief
• General, Theory of operations

Overall, there is a ton of information there, but it's a very flat structure. For me (as a relatively new OT member), I'd like to see more hierarchy

[mdhayter]

Maybe it is covered by the topgen/reggen and FPGA topics but could also see: Hardware engineer, wanting to make a chip/FPGA with different set of IPs from provided top_*

[domrizz0]

I think re: hierarchy, there are (at least, today) two things I really want to see pop out. 1) How-to get started; i.e. what do I need to in simple fashion to grab an image and flash it onto an affordable, approachable FPGA platform. 2) the HW / IP development stages metrics somewhere upfront.

[tjaychen]

I'm looking at ways to improve the current OT documentation (as seen at https://docs.opentitan.org). Whilst we do have a decent amount of documentation I don't think it's always clear where to look to find information on particular topics if you're not already familiar with the project. I intend to propose some restructuring and identify any gaps where things need writing, improving or updating.

As a first step I wanted to assemble some documentation 'user stories', a brief description of the kinds of people who may be using the documentation and what they're aiming to do. We'll take a look at the current structure with each of these in mind as a way to guide the restructuring.

I've done an initial set below, please edit this to add more (or comment if you don't have edit permissions). Any more detailed feedback or suggestions is also welcome.

User Stories:

• General, new to the project want to understand how to ‘get going’
• General, wanting to setup an OT environment for initial trial/testing purposes (either in sim or FPGA)
• General, wanting to get to grips with what OpenTitan provides with deep dives into topics of interest
• General, wanting to understand the status of the project (e.g. what V1/D1 etc means, which block is in each, status dashboards for regressions/lint/implementation)
• Software engineer, wanting to understand the build process
• Software engineer, implementing software (e.g. DIF/driver) for a new IP block
• Software engineer, writing software using existing libraries/DIFs
• Software engineer, wanting to understand the details of a particular IP block interface and workings
• Software engineer, interested in the software stack (What OT firmware does, how boot process works etc)
• Hardware engineer, wanting to implement a new IP block
• Hardware engineer, wanting to understand how a current IP block works
• Hardware engineer, wanting to understand the topgen/reggen processes
• Verification engineer, wanting to run regressions, both full/CI and specific tests or target specific blocks
• Security researcher, wanting to understand the OT security model

i really like this breakdown. I might add for "hardware engineer", the following categories

• how to template a module for more flexibility? understanding the costs of templating
• how to tweak the hjson for a slightly different top level (this is probably part of the topgen category)
• along the lines of security model, we really do need a documentation that just...explains the chip. Memory addresses, what it does, rational for various things. This stuff is spread all over right now, and at some point we need to consolidate them into something cohesive.