Add more details and a concrete proposal for KEP-5

Signed-off-by: Joe Beda <joe.github@bedafamily.com>

1 files changed, 69 insertions, 19 deletions

diff --git a/keps/sig-contributor-experience/0005-community-site.md b/keps/sig-contributor-experience/0005-community-site.md
index 0768c0d4..66acb955 100644
--- a/keps/sig-contributor-experience/0005-community-site.md
+++ b/keps/sig-contributor-experience/0005-community-site.md
@@ -61,30 +61,47 @@ Specifically, building a site that can take advantage of the KEP metadata will b
 
 ### Goals
 
-* Provide a new site (`community.kubernetes.io`? `contrib.kubernetes.io`?).
-* Publish information that is currently in the [community repo](https://github.com/kubernetes/community).
+* A community facing portal to collect information for those actively working on upstream Kubernetes.
+* An easy to remember URL. (`community.kubernetes.io`? `contrib.kubernetes.io`?)
+* A streamlined process to update and share this information.
+  Ownership should be delegated using the existing OWNERS mechanisms.
+* A site that will be indexed well on Google to collect markdown files from the smattering of repos that we currently have.
+  This includes information that is currently in the [community repo](https://github.com/kubernetes/community).
+* Provide a place to launch and quickly evolve the contributor handbook.
 * Build some simple tools to enhance discoverability within the site.
   This could include features such as automatically linking KEP and SIG names.
 * Over time, add an index of events, meetups, and other forums for those that are actively contributing to k8s.
 
 ### Non-Goals
 
-* Discover and bring together information from multiple orgs/repos.
+* Actively migrate information from multiple orgs/repos.
+  This should be a place that people in the community choose to use to communicate vs. being forced.
 * Create a super dynamic back end.  This is most likely served best with a static site.
 * Other extended community functions like a job board or a list of vendors.
 
 ## Proposal
 
-TBD.
+We will build a new static site out of the [community repo](https://github.com/kubernetes/community).
 
+This site will be focused on communicating with and being a place to publish information for those that are looking to contribute to Kubernetes.
+
+We will use Hugo and netlify to build and host the site, respectively. (Details TBD)
+
+The main parts of the site that will be built out first:
+* A main landing page describing the purpose of the site.
+* A guide on how to contribute/update the site.
+* A list and index of KEPs
+* A place to start publishing and building the contributor guide.
 
 ### Risks and Mitigations
 
-<!--
-What are the risks of this proposal and how do we mitigate.
-Think broadly.
-For example, consider both security and how this will impact the larger kubernetes ecosystem.
--->
+The main risk here is abandonment and rot.
+If the automation for updating the site breaks then someone will have to fix it.
+If the people or the skillset doesn't exist to do so then the site will get out of sync with the source and create more confusion.
+
+To mitigate this we will (a) ensure that SIG-contributor-experience is signed up to own this site moving forward and (b) keep it simple.
+By relying on off the shelf tooling with many users (Hugo and Netlify) we can ensure that there are fewer custom processes and code to break.
+The current generation scripts in the community repo haven't proven to be too much for us to handle.
 
 ## Graduation Criteria
 
@@ -98,14 +115,47 @@ Hopefully the content previously contained in [umbrella issues][] will be tracke
 
 ## Implementation History
 
-## Drawbacks [optional]
+## Drawbacks
+
+The biggest drawback is that this is yet another thing to keep running.
+Currently the markdown files are workable but not super discoverable.
+However, they utilize the familiar mechanisms and do not require extra effort or understanding to publish.
+
+The current mechanisms also scale across orgs and repos.
+This is a strength as the information is close to the code but also a big disadvantage as it ends up being much less discoverable.
+
+## Alternatives
+
+One alternative is to do nothing.
+However, the smattering of markdown through many repos is not scaling and is not discoverable via Google or for other members of the community.
+
+The main alternative here is to build something that is integrated into the user facing kubernetes.io site.
+This is not preferred for a variety of reasons.
+
+* **Workflow.** Currently there is quite a bit of process for getting things merged into the main site.
+  That process involves approval from someone on SIG-Docs from an editorial point of view along with approval for technical accuracy.
+  The two stage approval slows down contributions and creates a much larger barrier than the current markdown based flow.
+  In addition, SIG-Docs is already stretched thin dealing with the (more important) user facing content that is their main charter.
+* **Quality standards.** The bar for the user facing site is higher than that of the community site.
+  Speed and openness of communication dominates for the community facing site.
+  Our bar here is the current pile of Markdown.
+* **Versioning and branching.** Much of the main user facing site is lined up on Kubernetes releases.
+  This includes archived versions and branches as we lock down a release.
+  None of this applies to the evergreen community facing site.
+* **Different tooling.** We may want to create specialized preprocessors as part of the community site build process.
+  This could include integrating our current expansion of sigs.yaml into Markdown files.
+  It may also include recognizing specific patterns (KEP-N) and creating automatic linkages.
+  Applying these to a part of a site or validating them across a larger site will slow creation of these tools.
+
+An alternative to building directly into the website repo is to build in some other repo and do some sort of import into the main website repo.
+There are serious downsides to this approach.
+
+* **No pre-commit visualization.** Netlifies capability to show a preview per PR won't work with a custom cross repo workflow.
+* **Higher latency for changes.** If the merges are batched and manually approved then there could be a significant time gap between when something is changed and when it is published.
+  This is a significant change from the current "pile of markdown in github" process.
+* **Opportunity for more complex build breaks.** If something is checked into a satellite repo it may pass all of the presubmit tests there but then fail presubmits on the parent repo.
+  This creates a situation where manual intervention is required.
+  Complicated pre-submit tests could be built for the satellite repo but those need to be maintained and debugged themselves.
+* **New tooling.** New tooling would need to be built that doesn't directly benefit the target audience.
+  This tooling will have to be documented and supported vs. using an off the shelf service like netlify.
 
-<!--
-Why should this KEP _not_ be implemented.
--->
-
-## Alternatives [optional]
-
-<!--
-Similar to the `Drawbacks` section the `Alternatives` section is used to highlight and record other possible approaches to delivering the value proposed by a KEP.
--->
\ No newline at end of file