lowRISC / lowRISC/opentitan

[doc] Documentation restructure & improvements

Open
#5,181 5 comments 0 reactions 2 assignees Assigned to @mundaym View on GitHub
Component:Doc Earlgrey-PROD Triaged Type:Enhancement
Dominant language
SystemVerilog
Stars
3.6k
Forks
1.1k
Avg merge
2d 22h
Merged PRs (30d)
141

Description

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

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.