Quickstart guide no longer quick
fitzthum opened this issue · 2 comments
It's great to see how committed people have been to updating the quickstart guide, but we are starting to have some organizational issues and in general the guide is becoming unwieldy both for people working on it and people reading it.
For starters we should probably split the quickstart into separate guides focusing on various aspects of the project. That said, let's make sure that we don't lose sight of the collective goals and interface of the project.
It might also be time to adopt a more serious documentation framework. Many CNCF projects use some kind of documentation that transforms markdown into an actual website. Is this worth the effort for us at this time? How would we host such a site?
It's great to see how committed people have been to updating the quickstart guide, but we are starting to have some organizational issues and in general the guide is becoming unwieldy both for people working on it and people reading it.
For starters we should probably split the quickstart into separate guides focusing on various aspects of the project. That said, let's make sure that we don't lose sight of the collective goals and interface of the project.
I agree and suggest make image encryption, troubleshooting and ephemeral storage into their own docs.
Image signing is on image-rs repo. Maybe I would move it to this repo.
It might also be time to adopt a more serious documentation framework. Many CNCF projects use some kind of documentation that transforms markdown into an actual website. Is this worth the effort for us at this time? How would we host such a site?
It's a good idea but I would not spend time on that at this point in time.
I'd like to propose the following as well:
Let's make the different technology stacks separate markdown pages. We can have the top readme contain just the common steps for the operator and then provide a list of links for the user to follow that would take them to the TDX, SEV, etc. page.
I like the idea of a pretty documentation page. I think it would be worth looking into a tool that converts the markdown. I'll do some research.