search

containernetworking / cni.dev

CNI website
https://cni.dev
Apache License 2.0
48 stars 55 forks source link

Migrating CNI content #23

Closed nate-double-u closed 3 years ago

nate-double-u commented 3 years ago

3rd attempt at a first pass of migrating CNI documentation. (Third time's the charm, this time: simplify!) fixes: https://github.com/containernetworking/cni.dev/issues/13

Deploy preview: https://deploy-preview-23--cni.netlify.app/

nate-double-u commented 3 years ago

Deploy preview: https://deploy-preview-23--cni.netlify.app/

Interesting pages in deploy preview: https://deploy-preview-23--cni.netlify.app/cni/ https://deploy-preview-23--cni.netlify.app/cni/spec/ https://deploy-preview-23--cni.netlify.app/cni/conventions/

nate-double-u commented 3 years ago

This is a much simpler way of versioning the CNI SPEC and CONVENTIONS. I still need to go through and correctly set links throughout the copy, but I think this method of versioning these two docs should be good moving forward.

edit: links updated.

nate-double-u commented 3 years ago

In the https://github.com/containernetworking/cni repo, we may want to open an issue regarding building this website, and discuss how we want to manage this information (i.e., Do we want to remove the copied files from that repo? Leave them there? Edit the files there to point to their corresponding files here? etc.). I'd like to avoid duplicated content if at all possible, as it adds to the maintenance burden, but I understand that the SPEC is the main artifact of the https://github.com/containernetworking/cni repo so may have to live in both locations.

nate-double-u commented 3 years ago

Content note:

Regarding the Documentation folder in the main repo:

nate-double-u commented 3 years ago

Inviting @zacharysarah to review.

zacharysarah commented 3 years ago

@nate-double-u 👋

Dual sourcing

the SPEC is the main artifact of the repo so may have to live in both locations.

Dual sourcing content isn't the way to go. In my opinion, publishing content on the website would be a better developer experience.

It's better to provide actual page names ("Specification", "Conventions", via a title attribute in the front matter of each respective page) rather than reusing the file name for the link text.

If for whatever reason SPEC.md and CONVENTIONS.md need to remain at the top level of the repo, link to them from the website with some context rather than publishing the files in both places. (I recommend publishing content authoritatively on the website, though.)

Top rail link

Change "CNI" to "Documentation".

Screen Shot 2020-11-03 at 9 11 40 PM

nate-double-u commented 3 years ago

Dual sourcing

the SPEC is the main artifact of the repo so may have to live in both locations.

Dual sourcing content isn't the way to go. In my opinion, publishing content on the website would be a better developer experience.

It's better to provide actual page names ("Specification", "Conventions", via a title attribute in the front matter of each respective page) rather than reusing the file name for the link text.

If for whatever reason SPEC.md and CONVENTIONS.md need to remain at the top level of the repo, link to them from the website with some context rather than publishing the files in both places. (I recommend publishing content authoritatively on the website, though.)

During the CNI Maintainers meeting this morning we discussed whether or not the SPEC and CONVENTIONS files should live in the CNI repo, or here. @squeed Suggested that because these files are the primary function of the CNI repo, that those files should remain there and that this website should link out to them.