Create new Documentation

[jboyd01]

In the November 2017 F2F we identified a need for augmenting the Service Catalog documentation. This item tracks the work we identified.

November Service Catalog F2F meeting minutes:
https://docs.google.com/document/d/1j6dTOC4avpNCYSbF2MnDHWvFIuN0DIicf1F4vRC1CiM

We need people to produce docs. Even if just in small chunks.

What kind of docs do we want to see?

• Kube concepts
• Why “reconcile” ?
• Update design docs - e.g. re-list
• Why service catalog?
• Our model and descriptions of the resources
• API docs
• Expand Walkthrough + tons of speaker note explaining whys/hows/…..
• How to do certain things? How do I relist?
• User-flow docs, “How to” docs…. User guide/tasks
• Integration docs - how does svc-cat fit in with the bigger kube picture?
• Integration with brokers
• Integration with legacy systems
• How to address brokers?
• Need non-UPS example/walkthrough since UPS is kind of special
• What is a UPS broker?

Concepts:

• Kube concepts
• Design docs
• Why svc-cat?
• API concepts

Guides

• Walkthroughs - more details
• Plugins if we have them

Tasks

• Using/passing parameters
• Pull parts of walkthrough + details
• Integration with particular brokers
• Adding brokers
• Setting up API aggregation and RBAC

References

• API docs

[jhcook]

@jboyd01 I would like to be involved in collating and maintaining documentation. @pmorie the relevant people should convene to decide a way forward since documentation templating tends to be opinionated.

[jeffchanjunwei]

hi @jboyd01 , how can i join？ I have sorted out some information about this.

[pmorie]

@jhcook I'd prefer not to make a group decision to move forward - if someone is interested in writing doc for one of the areas mentioned here, I'd happily merge it and we can make a group decision later about reformating, etc.

@jeffchanjunwei Is there a particular area you're interested in documenting?

[pmorie]

@jhcook what do you think about adding doc for adding a broker to the catalog?

[jeffchanjunwei]

hi @pmorie , sorry for late reply. Maybe the following conceptes are suitable for me. Very honored if I could join in .

Concepts:

• Kube concepts
  (Not sure the specific concepts. I think it describe the relation between svccat and kube？)
• Design docs
• Why svc-cat?
• API concepts

References:

• API docs

[jeremyrickard]

@jboyd01 if you don't mind, I'm going to submit some discrete/trackable documentation issues out of this and link them back to this issue. That way, we can annotate them with appropraite labels like Help Wanted and people can use #dibs to claim them.

@jeffchanjunwei we are starting a little documentation improvement working group. So far, it's me, @jhcook, @carolynvs, and @arschles. We're discussing on the Kubernetes slack. Once we break down this issue into manageable chunks, comment on one you want with #dibs and have at it!

[jboyd01]

@jeremyrickard sounds like a great way to start, thanks!

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[mszostok]

/remove-lifecycle rotten
/lifecycle frozen

[sftim]

Also see kubernetes/website#30645

[mrbobbytables]

This project is being archived, closing open issues and PRs.
Please see this PR for more information: kubernetes/community#6632