search

notaryproject / notaryproject.dev

Notary Project Website
https://notaryproject.dev
Other
25 stars 57 forks source link

Restructured the layout of the current documentation #312

Closed Roseline-Bassey closed 12 months ago

Roseline-Bassey commented 1 year ago

This PR is an implementation of the proposed docs structure #306 for the Notary Project.

The documentation layout has been restructured in this order :

Project overview Contributing.md Notation >

Troubleshooting

Developer documentation (Securely develop plugins for Notation, Securely deploying Notation, Experimental features, and Notary project specifications and requirements have been moved to developer docs)

FAQ

netlify[bot] commented 1 year ago

Deploy Preview for notarydev ready!

Name Link
Latest commit 12f160bd3d5cdafc7a269f3cfbaa28abe5cadf0e
Latest deploy log https://app.netlify.com/sites/notarydev/deploys/64ff6e831bbd520008770d97
Deploy Preview https://deploy-preview-312--notarydev.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

zr-msft commented 1 year ago

fixes #306

Roseline-Bassey commented 1 year ago

Hi, @zr-msft, thanks for the comment. I have updated the PR to incorporate your suggestions. Please kindly review.

Roseline-Bassey commented 1 year ago

Thank you, @zr-msft

zr-msft commented 1 year ago

@Roseline-Bassey you'll need to rebase your branch for this PR and resolve any conflicts before we can merge this

Roseline-Bassey commented 1 year ago

Hi, @zr-msft I have rebased and force-pushed to my branch. On my local Git, the rebase output shows that it "Successfully rebased and updated refs/heads/refactoring-docs-branch." There was no conflict on my local git after rebasing and before submitting the pull request but on this PR page GitHub says: 'This branch has conflicts that must be resolved" I am wondering if I pushed the PR wrongly and what can I do to resolve the conflict.

zr-msft commented 1 year ago

Hi, @zr-msft I have rebased and force-pushed to my branch. On my local Git, the rebase output shows that it "Successfully rebased and updated refs/heads/refactoring-docs-branch." There was no conflict on my local git after rebasing and before submitting the pull request but on this PR page GitHub says: 'This branch has conflicts that must be resolved" I am wondering if I pushed the PR wrongly and what can I do to resolve the conflict.

did you fetch the latest from upstream?

git fetch upstream
git rebase upstream/main
Roseline-Bassey commented 1 year ago

On the main branch, I executed git fetch upstream

Then on my branch, I executed: git rebase main

zr-msft commented 1 year ago

On the main branch, I executed git fetch upstream

Then on my branch, I executed: git rebase main

you need to run git rebase upstream/main on your branch. You ran the equivalent of git rebase origin/main

Roseline-Bassey commented 1 year ago

Thanks, @zr-msft This PR is updated and is without any conflicts.

FeynmanZhou commented 1 year ago

This PR is an implementation of the proposed docs structure #306 for the Notary Project.

The documentation layout has been restructured in this order :

Project overview Contributing.md Notation >

Troubleshooting

Developer documentation (Securely develop plugins for Notation, Securely deploying Notation, Experimental features, and Notary project specifications and requirements have been moved to developer docs)

FAQ

@Roseline-Bassey What's the reason that we use Notation as the top-level name of this chapter? @zr-msft Do you feel this is a reasonable directory structure?

Roseline-Bassey commented 1 year ago

Notation is used as a top-level name to serve as a central directory for all content related to notation and for better organization of content and versioning. @FeynmanZhou

zr-msft commented 1 year ago

@FeynmanZhou the content at the root level is related to the Notary Project in general. Content in the notation dir is specific to notation. There could be a future state where this another client that does notary signatures that would be a peer to notation and have a dir at the same level. Content at the root level for the Notary Project would apply to both clients.

@toddysm please let me know if you disagree

FeynmanZhou commented 1 year ago

@FeynmanZhou the content at the root level is related to the Notary Project in general. Content in the notation dir is specific to notation. There could be a future state where this another client that does notary signatures that would be a peer to notation and have a dir at the same level. Content at the root level for the Notary Project would apply to both clients.

@toddysm please let me know if you disagree

There is no plan for developing another client as a peer based on the Notary Project specifications in the near future. I would suggest focusing on a certain thing (currently there is Notation only) and designing the documentation directory to be more straightforward. In case another client is planned in the future, we could refactor the documentation directory accordingly.

I will consult other maintainers @iamsamirzon @toddysm @yizha1 about this new documentation directory change.

zr-msft commented 1 year ago

@FeynmanZhou the content at the root level is related to the Notary Project in general. Content in the notation dir is specific to notation. There could be a future state where this another client that does notary signatures that would be a peer to notation and have a dir at the same level. Content at the root level for the Notary Project would apply to both clients. @toddysm please let me know if you disagree

There is no plan for developing another client as a peer based on the Notary Project specifications in the near future. I would suggest focusing on a certain thing (currently there is Notation only) and designing the documentation directory to be more straightforward. In case another client is planned in the future, we could refactor the documentation directory accordingly.

I will consult other maintainers @iamsamirzon @toddysm @yizha1 about this new documentation directory change.

@FeynmanZhou Having Notation content clearly separated from Notary Project content helps distinguish the difference between the two. As a side benefit, it also makes it easier for other clients in the future.

Having a more streamlined content directory structure would solve some complexity problems, but it introduces others. For example, versioning the content for new Notation releases. If we create a version 1.1 of the docs and we tightly couple Notary Project content with Notation content, does that mean both Notary Project and Notation are at 1.1? If its only for Notation, how can we show that if content is mixed together?

yizha1 commented 1 year ago

My comments:

The first entry includes documents for Notary Project, like overview, specifications (current it is under Concept), contributing, FAQ for Notary Project and folders for sub-projects, for example Notation at this moment. The order of the following items could be different.

FeynmanZhou commented 1 year ago

@Roseline-Bassey @zr-msft @yizha1 @notaryproject/notaryproject-notation-maintainers

I would suggest we design the top-level directory structure for different roles or different user phases. It will shape the content structure more logical and friendly. Typically, there will be four major roles or stages:

Newbies -> users -> developers -> contributors

When people are new to the project, as newbies they may want to see the project introduction, learn basic concepts, and run a short demo (quick start) in the investigation or evaluation stage. So the following three chapters should be placed at the beginning:

Next, newbies will become users if the tool (Notation CLI) meets their needs after their first trial, they will explore more detailed use cases and guidelines in the user guides:

In the third phase, some expert users are more likely to be developers who may want to develop Notation itself or extend the ecosystem by adding a new plugin. Some others may consider building their own client based on the Notation go library. Developer guides should be designed for developer types of users in this phase.

Next, developers are capable of contributing to the project. They may explore how to contribute to the Notary Project and engage more with the community. The contributing guides should be designed for contributors and developers in this phase.

Last, Spec and FAQ are generic content for any type of user. These two chapters are similar to the role of a "dictionary" which provides references. These two chapters are generally placed at the bottom of the directory.

zr-msft commented 1 year ago

@yizha1 I'm fine updating the order

@FeynmanZhou i understand your approach about user types and progression, but I don't think that works for organizing the docs. Specifically, it causes the following issues:

I'll reiterate my concerns from my previous comment: In this tightly-coupled structure, what happens when Notation releases a new version, but the Notary Project is the same version? Does the whole project assume the version of Notation? What happens in the future if there is another client under the Notary Project that needs to be documented with its own version independent of Notation?

FeynmanZhou commented 1 year ago

@zr-msft Thanks. I understand your major concern, which is about the versioning problems if we mix different sub-projects in the documentation.

Actually, the term Notary Project is the brand name and refers to all sub-projects as described in https://github.com/notaryproject/.github/issues/35 (TLDR, See summary below). So Notary Project will not be versioned separately. All sub-projects in the Notary Project organization will have their own versioning, but those sub-projects should be documented on the website. Most of the sub-projects are created for Notation.

The name of the GitHub organization is "Notary Project". When used this term has an all-encompassing meaning and will refer to the GitHub organization, the community, all specifications, and all the repositories under the organization including tools that are released by the community.

To resolve your questions below, I would suggest the current directory structure focuses on Notation at this stage since Notation is the only core sub-project. Most of the documentation content is also created for Notation. If there is another client tool in the future, we can design a separate documentation entry and provide a menu accordingly.

In this tightly-coupled structure, what happens when Notation releases a new version, but the Notary Project is the same version? Does the whole project assume the version of Notation? What happens in the future if there is another client under the Notary Project that needs to be documented with its own version independent of Notation?

zr-msft commented 1 year ago

@FeynmanZhou I understand we have a current state where notation is the primary way users interact with signing/verifying artifacts with Notary signatures. I also understand that Notary Project is an umbrella term that encompasses all sub-projects.

If we move forward with a simplified directory structure focused on notation here's what it will look like:

Then a later version:

Are you all planning on releasing all the sub-projects under The Notary Project as a system release with the same version? For example, notation, notation-go, notation-core-go, etc are all released at the same with the same version e.g. 1.1.0. If so, the above makes sense.

If not, the following becomes confusing:

I understand the desire not to over-complicate the directory structure. Tying the version to the notation version works for the majority of the current content, but we're going to see issues for work we already have queued up ( #314 ).

@toddysm @sajayantony @yizha1 can you weigh in on this, please?

FeynmanZhou commented 1 year ago

Are you all planning on releasing all the sub-projects under The Notary Project as a system release with the same version?

All sub-projects will have their separate versioning not only notation, notation-go, notation-core-go. For Go library docs, they are maintained on Go doc so we don't have too much additional content needs to be added to the website. For other development guides, I suggest maintaining the latest version only since it doesn't change along with different Notation versions generally. We can state this in the development docs.

https://notaryproject.dev/docs/1.1/developer/go-library is the doc for developing against the go library when version 1.1 of notation is released. The version in the URL has no connection to the version of the go-library, but looks like it does. It's not obvious that the version is only tied to notation.

We will maintain only two versions of all sub-projects including "N" and "N-1" as described in the RELEASE MANAGEMENT. So I would expect the default URL without a version number that implies the latest version, such as https://notaryproject.dev/docs/developer/go-library. Accordingly, users only specify a version when they want to explore the docs in an N-1 version, such as https://notaryproject.dev/docs/$last-version/developer/go-library

https://notaryproject.dev/docs/1.1/overview/ is the doc giving an overview of The Notary Project when version 1.1 of notation is released. The content has no relation to the version in the URL, but it looks like it does. It could easily be confusing as the doc giving an overview of The Notary Project at version 1.1 of The Notary Project, which is not true.

This is a bit confusing indeed since Notation and Notary Project are tightly coupled in the project overview doc. The potential solution could be focused on the Notation but briefly introduce Notary Project and link to .github README. There will be a comprehensive introduction to the overall Notary Project. We can also state the Notary Project doesn't have separate versioning accordingly.

FeynmanZhou commented 1 year ago

Let's discuss the version control and new directory structure in the Notary Project community meeting later : )

toddysm commented 1 year ago

After the discussion in the Notary Project Community meeting, I like the proposal from Sajay to have a project (system release) version that wil be used for the documentation. The system release is a combination of several things (spec, CLI, libraries) that can have different versions - we can describe those in the system release overview. For the current release, we can either avoid the version in the documentation URL or use 1.0 - IMHO for this release doesn't matter too much because everything will be 1.0.0. In the future we should have this clearly described in the Overview.

iamsamirzon commented 1 year ago

After the discussion in the Notary Project Community meeting, I like the proposal from Sajay to have a project (system release) version that wil be used for the documentation. The system release is a combination of several things (spec, CLI, libraries) that can have different versions - we can describe those in the system release overview. For the current release, we can either avoid the version in the documentation URL or use 1.0 - IMHO for this release doesn't matter too much because everything will be 1.0.0. In the future we should have this clearly described in the Overview.

I am supportive of this idea. This is in line with how we did the first few alpha releases, refer alpha-1 , alpha-4, and even RC-1

zr-msft commented 1 year ago

If we agree to a system release per the message from @toddysm, I propose we update the directory structure refactor to the following:

docs/
    notary-project-overview.md
    notary-project-concepts.md
    faq.md
    user-guides/
        quickstart.md
        installation-guides/
            cli.md
            uninstall.md
        tutorials/
            trust-policy.md
        how-to-guides/
            manage-signatures.md
            ...
            registry-authentication.md
        notation-cli-reference/
            notation_certificate-add.md
            ...
            notation.md
        troubleshooting.md
    developer-guides/
        notation-plugin-developement.md
        notation-core-go-development.md
        notation-go-development.md
    contribute.md
    notary-specification.md

This incorporates many points of feedback and suggestions from myself as well as @FeynmanZhou @Roseline-Bassey and @yizha1

@toddysm @FeynmanZhou @Roseline-Bassey @yizha1 @sajayantony @iamsamirzon what do you think?

Roseline-Bassey commented 1 year ago

Thanks for the proposal @zr-msft. I suggest moving quickstart guides to the top level in place of faq.md. I have also included a glossary.md page since I submitted a PR about it at #326. Let me know what y'all think.

docs/
    notary-project-overview.md
    notary-project-concepts.md
    quickstart guides/
         Sign and validate a container image
         Sign and validate a non-container image
    user-guides/
        installation-guides/
            cli.md
            uninstall.md
        tutorials/
            trust-policy.md
        how-to-guides/
            manage-signatures.md
            ...
            registry-authentication.md
        notation-cli-reference/
            notation_certificate-add.md
            ...
            notation.md
        troubleshooting.md
    developer-guides/
        notation-plugin-developement.md
        notation-core-go-development.md
        notation-go-development.md
    contribute.md
    notary-specification.md
   faq.md
   glossary.md
FeynmanZhou commented 1 year ago

Agree with the proposal from @toddysm @zr-msft and the latest directory structure suggested by @Roseline-Bassey.

Just one note, for those proposed docs without content in chapters like developer-guides, please avoid creating empty placeholder .md files in this PR. We can send follow-up PRs to those docs until we have certain content.

yizha1 commented 1 year ago

+1 to @toddysm 's proposal , and directory structure details shared by @zr-msft @Roseline-Bassey .

Thanks @zr-msft and @Roseline-Bassey for driving this forward.

zr-msft commented 1 year ago

@Roseline-Bassey Any updates the progress of this PR?

Roseline-Bassey commented 1 year ago

I'm currently working on updating this PR now. @zr-msft

iamsamirzon commented 1 year ago

Where can I see the latest preview of the .dev website?

Roseline-Bassey commented 1 year ago

Here's the latest preview of the website: https://deploy-preview-312--notarydev.netlify.app/ cc: @iamsamirzon

zr-msft commented 1 year ago

@Roseline-Bassey can you rebase again when you have a chance and resolve the conflicts?

Roseline-Bassey commented 1 year ago

I have rebased this branch @zr-msft

iamsamirzon commented 1 year ago

I am unable to leave inline comments, so summarizing here some feedback on FAQs. Originally this section was meant to refer to only things related to the new specification and its implementation Notation, but recently we added FAQs about the notary client, notation client, and the overall notary project. Consequently every prior use of "Notary" has to be revisited on this page and website , so we can either change it to "Notary Project", "Notary Specification", or "Notation" client. For instance refer the 4 FAQs under the sub-heading https://deploy-preview-312--notarydev.netlify.app/docs/faq/#trust-store-and-trust-policy . They should all be referring to Notation Specification

FeynmanZhou commented 12 months ago

Hi @Roseline-Bassey , the updated version looks good to me. Thanks for your patience. Could you ps resolve the conflict?

FeynmanZhou commented 12 months ago

@zr-msft @Roseline-Bassey I feel this article could be moved to the chapter "User guides" since only Notation users may take care of this configuration. What's your opinion? image

Roseline-Bassey commented 12 months ago

Yes, I agree. The article can be included in the how-to guides under the User Guides. @FeynmanZhou