[ACTION] Move documentation to a dedicated docs website #65
Comments
guidemetothemoon
added
kind/documentation
|
@nikimanoledaki FYI😊 |
|
Thank you for these suggestions! Doks does look awesome - let's go for it!! 😄 |
|
Great, I will start looking into this in the coming days |
|
@guidemetothemoon will you need a domain for the docs website? We can request this as well as the one for the Grafana dashboard cc @leonardpahlke |
|
@nikimanoledaki yes, we will definitely need a domain. Which one would you like? One of the suggestions was to have a subdomain under |
|
fyi @cjyabraham |
|
@guidemetothemoon @nikimanoledaki did we explored the option of integrating it into our current website tag-env-sustainability.cncf.io with just sub pages? The templates has these capabilities (cc @cjyabraham). I am thinking a bit a long the lines of https://glossary.cncf.io/, as a sub page for WG Green Reviews part of the TAG website. |
|
I guess whether to integrate it into tag-env-sustainability.cncf.io or set it up as its own website will depend on its requirements. How many pages is it? Does it require versioning so that people can review the docs according to which version of the software they are using? If we integrate it into tag-env-sustainability.cncf.io, could the pages be hosted in the same repo or do they have to stay in this repo (both are possible but the latter adds complexity)? Does it require its own branding? |
|
Here I think that Green Reviews leads should have an opinion: @nikimanoledaki @AntonioDiTuri @rossf7 To me it makes sense to keep documentation in this repo for consistency and in order to gather everything related to the working group's activities in the same place. If we take TAG App Delivery as an example, they do also have separate websites for things related to the TAG itself and f.ex. for OpenGitOps project. I'm not against putting it under the main website either, but in that case I think it's best to keep documentation in this repo to avoid confusion and repo switching for contributors. |
|
I agree with @guidemetothemoon's points! We should definitely keep the Green Reviews WG docs in this repository. +1 - given the project Roadmap, it may require its own branding at some point, but we have not discussed this yet. We could add this to the Roadmap around Q3 when we reassess the direction of the project. I wanted to add that the TAG App Delivery/GitOps WG initiative OpenGitOps is a CNCF Project in itself (fun fact! 😄). However, this is not something that we are considering for the Green Reviews WG project at the moment. I am also not opposed to starting with the documentation as part of the main website as long as the files can remain in this repository. We can always split this later if needed. :) I am not familiar with how to push from two separate repos with any of the docs templates - is there an easy way to do this? |
One way to accomplish this would be to add this repo as a git submodule inside the tag-env-sustainability repo, similar to how the docsy theme is currently included. We may need to use symlinks to link in just the directories we need into the /content/ dir. For automating updates, we could possibly rig together a GH Action to create a PR against the tag-env-sustainability repo each time this repo is updated. This is complex and tricky to remember how it all works but I'm not sure there's an easier way. |
|
Thanks @cjyabraham! I just discussed this with @AntonioDiTuri & @rossf7. While we are not opposed to having this be part of the TAG website (especially to unblock us), we concluded that it would be clearer and less confusing if Green Reviews WG had its own standalone docs website. The project itself is quite complex and it may be easier for newcomers if it's encapsulated in its own docs website. The project aims to lower the barrier to entry for users who would like to use this project as a reference architecture. This is similar to the Green Metrics Tool (https://docs.green-coding.io/) by Green Coding Berlin (https://www.green-coding.io/). It would also be good to follow the general best practice of keeping the docs website separate from the org website. One issue is that we are also creating a public instance of Grafana and we need a DNS entry for that too. At the moment we are considering using What do you all think? From my side, I need a bit of time to think this through before making a decision. |
|
Would it be possible to have something like:
So that we keep one domain name and we can file different content under it? |
|
The choice of a suitable, at best most minimal static site generator for a docs website of the Green Reviews WG aside, the multiple naming intentions do not need to remain a blocker. While path-based routing is usually a frill and leads to all the interesting side effects of web applications sharing the same domain, as in browser security context (for cookies), there is always the possibility to use further subdomains in the hierarchical DNS. Anything like
or
or
and the likes offer ways to work around the naming clash. For shared maintenance of the (delegated sub-)zone, it further appears useful to consider using octodns-sync · Actions · GitHub Marketplace for collaboratively shared maintenance with audit trail in a private repository and a PR-bot-driven workflow. |
nikimanoledaki
added this to the [Q2 24] Deploy, Run, Report: Automate the sustainability footprint pipeline milestone
|
Related domain naming issue: #31 In yesterday's WG Green Reviews meeting, we reached consensus on the following subdomains:
Would it be possible to request both of these please? @guidemetothemoon @leonardpahlke Thank you!
Interesting, definitely something we can look into, thank you @almereyda! |
|
Do we have a target for |
|
I've started on the getting the docs website ready. Will update you once PR is published. |
github-project-automation
bot
moved this from In Progress
to Done
in TAG-Environmental-Sustainability
|
Reopened this since the documentation website is not up yet. |
|
There is also the option to move the documentation as mentioned before to the TAG ENV website and forward Benefits of keeping one website:
Thoughts? |
@nate-double-u this should not be a problem right? |
|
Adding a redirect shouldn't be a problem, though I'm not exactly convinced of the need;
This is true; the In this case, I don't see the need for another website, and we should not create a new subdomain. |
|
For the dashboard, we can use Hugo or Netlify's redirect features to have something like |
|
Thanks Nate, this sounds good to me! |
|
@nikimanoledaki @AntonioDiTuri @guidemetothemoon @rossf7 -- feel free to drop a +1 or objections sometime next week so we can move forward with the docs website. Thanks 🙌 |
|
I think that the WG lead team (@rossf7 @AntonioDiTuri @nikimanoledaki) should give their feedback here. A general feedback from me would be that, if creating additional websites is a restriction/limitation from CNCF, then we should clarify it really well from the start or define a process on how such decisions should be taken and confirmed, because a significant amount of work has been done to create the current version of the documentation website for the WG, based on the overall decision which was taken earlier. Arguments for why a separate website was preferred are provided in this issue, specifically #65 (comment) But, of course, if it's a no-go then we can't do much about it. I think that the challenge of switching between different repos to look for and maintain documentation for this WG would still stand, but maybe it'll not be a problem in reality. It's of course more sustainable to use existing website instead of creating additional ones so I'm not against this option, but it would be good to clarify the process going forward to avoid this type of rework in case such need arises again at any later point. |
|
I agree with @guidemetothemoon if there is a restriction on creating additional websites it would have been good to know this earlier. The reasoning in #65 (comment) still makes sense to me. However if this isn't an option we will have to change the approach. I can see the benefit of being able to reuse the translation work being done on the main TAG website.
@nate-double-u @leonardpahlke For the dashboard we have an elastic IP from Equinix. So we will redirect to that IP from Hugo / Netlify? That should work provided there are no browser warnings etc. This means we wouldn't need cert-manager in the cluster which I like from a simplicity POV. |
|
I agree with what @guidemetothemoon & @rossf7 said - we based the decision on different assumptions. Encapsulating a project separately to the org still makes sense to me as well.
Would the WG Green Reviews docs remain under Merging the docs website adds some work to automate fetching the information from this repository but this should be doable. +1 that this policy should be documented to factor it earlier in the decision-making process. Changing this now requires double work and time, which is scarce, and it would be unfortunate to scrap @guidemetothemoon's awesome docs website contribution. ✨ The arguments in favor of maintaining a single docs website make sense regarding dependency updates, consistency, and maybe discoverability. |
|
Thanks for the comments.
AFAIK, there is no limitation to have a max of one website per TAG. One website just makes things easier and more cohesive.
I don't see this being a problem. It is often the case that you have more than one repository per open source project. Its a small "cost" for making things easier (points raised before)
The website would move to the
I don't see this being a problem. Doc PRs are separate of the code contributions anyway. WG Chairs & TL have access by default to both repos.
We could add a document like this https://github.com/cncf/tag-env-sustainability/blob/main/governance/communication-channels.md or add to the linked file a paragraph about websites. Thoughts?
Adding to a subpage to make it more accessible & a second one to another IP should not be a problem as @nate-double-u commented before. (comment) |
|
Okay. @guidemetothemoon let's revert #89 and open a new PR to add the contents to the TAG ENV website. I am happy to do it or team up with you @guidemetothemoon. Apologies Kristina, that I have not followed up on my comment #65 (comment), now we had a bunch of extra discussions & work on your side to get the documentation website up. |
I disagree with this point - I think we should keep the docs as part of this repo. At least we should discuss this further as a WG until we reach a general consensus. It is recommended to add documentation along with code. Here is a very good example: https://github.com/cncf-tags/green-reviews-tooling/pull/81/files. Moving the docs to a separate repository adds toil to the contribution process. |
|
+1 to what @nikimanoledaki said. I also think that documentation should be kept together with the platform/application being built. |
|
Is it possible to look into automation that point to the content from the docs dir in this repo into the subdirectory of the main TAG website? Some frameworks make this easier than others, I don't know about the one that we use. WDYT? |
|
There is a comment above about keeping the docs' website separate, #65 (comment). |
|
I would suggest adding a new requirement to the TAG governance that says that when we document code, the documentation must be next to the code. |
|
This should be inline with your comments @nikimanoledaki @guidemetothemoon. And, in general, a good thing to do in software eng projects. |
|
I spoke with Kristina, Niki and Ross briefly earlier today to move forward here. We would prefer to host a website separate from the TAG ENV website.
If there are requirements maintaining just one website per TAG; we should document this somewhere 👍 @nate-double-u @krook -- does this work for you? It should be easiest for all. The website is already merged and part of this repo: https://github.com/cncf-tags/green-reviews-tooling/tree/main/website 🙌 (fyi, @krook we already have a servicedesk issue opened for this one 😉) |
I appreciate that work has already been done, but moving that content into the existing TAG site shouldn't be that much additional work; they're both set up as Hugo/Docsy sites, correct? I'm more concerned about the string of subdomains that we're suggesting.
For projects, and I understand that TAGs are different, we've had a long standing suggestion that code and documentation be separate (see: Repository setup).
I agree that more documentation is better. In this case, I'm not sure we've had a request for a multi-subdomain like this before. I think we've only got one multi-level subdomain setup, teststats.cncf.io, but that's a different kind of tool than what is being proposed here. I may be wrong, but I'm not sure other tags have asked for a second website yet either. My other concern about using a new subdomain versus a folder structure is that any updates have to be made through a ticket with LFIT, whereas using a folder structure gives the TAG full control in a self-service manner, meaning you can change things as you see fit.
I think the service desk ticket being referred to is CNCFSD-2264, which I closed as "won't do," mostly due to my concern around the chained subdomain, and the other arguments I've outlined here (note: my closing it doesn't shut down the conversation). Correct me if I'm wrong about which ticket you're referring to. |
|
Looking at this again. Thanks Nate, for your comments. So in summary…
All in all, arguments extending the existing documentation with documentation for WG Green Reviews outweights arguments for setting up a new docs website. |
|
@leonardpahlke thank you for sharing your proposal for the docs website - I'm confident that we'll find a good home for the docs soon 👍 I like the idea of having the docs under Regarding the website structure, the headers are currently: Would we add
Hm this is the only thing that I disagree with - separating docs from code would most likely hinder the project. The Green Reviews WG project is small enough to have the docs close to the code. It is far too small to split this up and would require double effort and cognitive load from both the open-source contributors. We have moved all the issues to Instead, I propose finding a way to point to the current repo |
|
@guidemetothemoon what do you think about adding a Hugo submodule that points to this repo's I'm open to creating a PR for it. |
|
@nikimanoledaki Yes, I think that this can be an option worth exploring. If you're swamped with other things I can take a look at it next week or so? +1 to that separating the docs and the code would potentially contribute to hindering the project, as mentioned in #65 (comment) |
Yes. Of course (and we should). The WG Green Reviews is a bigger effort - it makes sense to place it more prominent on the website and make it more accessible. |
For my part, this was discussed in extensive length. PTAL @kevin-wangzefeng @TheFoxAtWork |
|
To be honest this has been a very challenging and time-consuming discussion with a significant level of unclarity. I suggest that we don't take any further steps on this until a definitive decision is taken and agreed upon by those who have the final saying in this matter. To me it sounds like the working group doesn't get to decide what approach works best for the group and its contributors in terms of maintaining their deliverables, which creates agitation and blockage to continue working further on the documentation. If it is a rule, a requirement from the CNCF/TOC that documentation that's produced by working groups in all cases must be added to the TAG repo and website, it would be helpful and valuable if this information can be provided and confirmed here by CNCF/TOC. Then it is clear that there is no room for decision-taking here and this must be done in the one and only way that is allowed. |
|
What @guidemetothemoon wrote resonates with me as well. As a Chair of this WG, I tried my best to coordinate with everyone involved during meetings and here. The decisions and outcomes that we agreed upon as a WG have been communicated above. Unfortunately, limitations coming from outside of the WG have not been clear during this decision-making process. Changing our course of action has been expensive in many ways. For the sake of the WG, I'm in favour of the quickest fix to close this issue and enable us to move on with the other work of the Green Reviews WG. If this means moving the docs to the TAG ENV website (this has been agreed upon already) + repository (we can skip creating a Hugo submodule) then let's do that. Personally, I would prefer to take a step back from coordinating/facilitating this issue. @leonardpahlke, please take this on as you have the most context of what's been communicated by all stakeholders. I trust your judgment here 👍 |
|
I believe there are some misunderstandings. There are good reasons why most other issues in the TAG are closed without any problems, and this one triggered more discussions. There is a WG Green Reviews Sync later today. It would be good to take a bit of time to walk through this issue. So we can learn from this 👍. |
|
Alright, so hosting a new website is not an option as summarized here. @nikimanoledaki proposed another option to host docs content in the green-reviews repository and import it as git submodule to the tag-env repository. Chris also commented about it before here. So, now we need to decide between:
Some of the arguments previously summarized still apply to this decision. Breakdown:
(Arguments for 1.) Arguments for integrating the documentation into the existing TAG ENV website:
(Arguments for 2.) Arguments for setting up a separate documentation website next to the TAG ENV website:
All in all, this is not as a clear decision as the previous one which was primarily based on subdomains & maintainability. Maintainability & complexity is still an argument but its less strong (IMO). Questions about the approach using gitsubmodulesFrom my side, I have two questions about the git submodules approach:
@nikimanoledaki @guidemetothemoon do you see any other open questions? All in all, it would be easier to move the content to the tag env repo right now, but the arguments around atomic PRs might be worth investing time in exploring the "submodules" option. If we have a good proposal on how to push aside the two questions outlined above - IMO it's no problem at all to have the docs in the green-reviews repo. |
|
As discussed in a parallel thread in Slack we will merge the PR that reverts website changes and puts docs into the original folder structure (#94). Since we have already got some questions and confusion around where the docs are it would be good to get it to a stable state first, until we land the final decision regarding git submodule. I will investigate how this would works with git submodule sometimes next week (unless someone else gets to it first). We will then create a new PR with changes depending on how we decide to integrate the WG docs into TAG ENV website (i.e. through git submodule or by migrating docs to the TAG ENV repo). |
With the deprecation of the design doc all the documentation for the work that's being done in Green Reviews WG is being moved to GitHub. To make it easier to digest all the information, onboard new contributors and in general make the overall documentation more visible and accessible we would like to create a dedicated website where the documentation can live.
The website will be linked to the doc files in this GitHub repo and will populate content accordingly.
We're already using Hugo as a static site generator for the TAG ENV website and we can do the same in this case as well. It's easy to set up and we can use the same folder structure and Netlify hosting configuration as we do for the TAG. There are also many templates available that are easily set up and adjusted as we need to.
Below are some suggestions for the docs templates we can use. Please note that things like menu sections and such are adjustable, preview website is just to give you an impression of how the website will look like, but we will adjust as needed content-wise.
The text was updated successfully, but these errors were encountered: