Update Docs #49
Update Docs #49
Conversation
✅ Deploy Preview for frolicking-manatee-96c0c8 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Rethink the structure of the docs as something that will be more useful to users. As such, get rid of outdated internal details on guest components, kata, and CAA. This commit leaves many of these new sections mostly empty. They will be extended in future commits. Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
4 times, most recently
from
42910ed
to
e805be1
Compare
Platform-specific setup will be added separately. Sample workload guide will be simplified with tabbed codeboxes. Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
5 times, most recently
from
214a080
to
16f8148
Compare
This is a much cleaner way to handle the configurations for different platforms. Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
from
16f8148
to
badd213
Compare
Add an overview of the hw that we support. This might be too much information for the top page, but at least it gives poeple a sense that the project has a broad scope. We can consider creating a separate hw section later. Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
3 times, most recently
from
e542f74
to
b932784
Compare
Add our existing trouble-shooting guide to the website. There are some improvements we could make to this doc, but for now let's just get it on the website Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
from
b932784
to
8d26e92
Compare
Let's get all of our features outlined before we add detailed material for each. Here we add authenticated registries and local registries. Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
2 times, most recently
from
dbf4efa
to
d6fe4b5
Compare
Move contributor guide to website. The website is mostly aimed at users, but our contributor guide is pretty good, so let's put it up here. Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
4 times, most recently
from
710715f
to
b31df10
Compare
This is mostly new content covering the design of CoCo. Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
from
b31df10
to
3ee83e9
Compare
Placeholder with some common use cases. Update with content later Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
Remove incomplete threat vectors page. We can add this back once there is some content, but I don't quite see how it fits. Rename personas to cloud-native-personas. Update main trust model document to include a plain description of the trust model rather a more generic definition of a trust model and goals for the trust model. The new text is mainly an overview. We may want to add something more empirical in the future, but this should help users understand what's going on. Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>
fitzthum
force-pushed
the
docs-overhaul-1
branch
from
d7b5565
to
702efa4
Compare
|
@confidential-containers/tsc @surajssd @mkulke Docs overhaul is ready for review. There are lots of changes here.
This is only the start. I have left a number of TODOs around. Most notably in the following sections
I think this PR provides a good base for contributions to the docs. There are probably lots of things we can improve about this PR and I am happy to take feedback but I also want to get the ball rolling so consider fixing suggestions in a follow-up. |
|
I went through the trust model docs, and those sections look great. |
Generally I want to try to converge the peer pods directions with the bare metal directions, but I didn't mean to delete the Azure docs. One place this could potentially live in the new layout is getting started -> pre-requisites -> hardware -> cloud -> azure Also is it valid separate out this stuff as pre-requisites? I'd like it if we just had setup steps and then people moved onto generic steps to install the operator and runt he workload. It seems like that can probably work if we add a |
putting it under pre-requisites feels a bit odd. Can we put it below getting started / installation / Azure? We could have similar instructions for other CSPs as siblings, or possibly a non-TEE qemu entry that covers everything from local k8s cluster installation to coco runtimeclass (in a similar copy/paste fashion as the azure docs). the installation page could still keep the more generic, brief installation instructions. |
|
@mkulke yeah seems tricky for the installation page that I currently have to capture everything in tab boxes. It can accommodate switching to different CRDs and CRs but the earlier steps where you download CAA don't really fit. For this PR can I just move the azure page as-is to a new top-level example section and then we think about how to handle peer pods? I don't really know how peer pods installation works. I suspect we probably want to add a cloud page to the installation section. Do we split it into two pages: cloud, and bare-metal (that are mutually exclusive)? Do we add another step for peer pods that is optional (before installation but after per-requisites)? I think after we get the peer pods stuff added some of the Azure stuff can go in pre-requisites; everything before installing CAA? wdyt? |
What I would suggest is to move the I would not recommend chopping up the documentation in generic and specific steps and leaving it to reader to puzzle it together (even if that means some redundancy) |
|
I feel pretty strongly about making the docs as generic as possible. Not doing so with the existing docs has created nothing but problems. With siloed docs maintainers only focus on their own sections which decreases quality and everybody ends up doing more work because individual sections are longer and more complex. This gets worse as we add more platforms and features. Let's not underestimate how painful redundancy can be. We've really struggled with this in the github docs. More fundamentally, we've struggled with making the project generic since day 1. If we keep the docs separate we enable ourselves to continue not really worrying about convergence which I think is a big mistake. Putting everything together is a good way to push in the other direction. It will definitely show us where we need to do some more work. That said, I understand that you guys have put time into the az doc in particular and that it is proven to work. That's why I suggest keeping it around in examples or some other place (even though that does also create some redundancy). I don't think it will be too puzzling for users to figure out the prerequisite steps. If it is then we probably need to make the project itself simpler. I don't want to put the az doc under the installation section as-is. It would be odd to have a pre-requisites and installation section next to another doc that also contains those steps. |
Lots of changes with the docs;
just a draft for now.