Separate design and user docs #1851
Conversation
erictune
force-pushed
the
dev_doc
branch
3 times, most recently
from
da11a8e to
0f7e8d9
Compare
| - **API documentation** | ||
| - in [api](../api) | ||
| - automatically generated REST API documentation | ||
|
|
There was a problem hiding this comment.
I'd also add links to the wiki, which contains the FAQs.
There was a problem hiding this comment.
added. Could not determine a pattern for what goes on wiki as opposed to somewhere else.
There was a problem hiding this comment.
I didn't put the API change guidelines there.
As for the rest, I find it a PITA to submit a PR to add a single bullet item. I put the FAQs on the wiki so that I could immediately add FAQ bullets after answering questions on IRC. I put the Community and Media pages there for a similar reason -- when someone posted or Tweeted something, I could add a bullet. For the most part, this information isn't tightly coupled to the code. It's true that non-maintainers have no way of directly adding to the wiki, but they could file issues about the content.
|
Could you leave forwarding docs in place for the design docs that have been moved? I posted links to them in many places. |
| - in [api](../api) | ||
| - automatically generated REST API documentation | ||
| - **Wiki** | ||
| - at [https://github.com/GoogleCloudPlatform/kubernetes/wiki] |
There was a problem hiding this comment.
For consistency with other bullets:
at [wiki](https://github.com/GoogleCloudPlatform/kubernetes/wiki)
|
Also, FYI/FWIW, I originally put the user documentation in the API documentation -- this was before the docs directory even existed IIRC. https://github.com/GoogleCloudPlatform/kubernetes/blob/master/api/kubernetes.raml Probably whatever content is still useful should be eventually moved out of the .raml file, so feel free to copy anything that's useful. |
|
This is cool. Do you have any ideas on where we can document internal APIs? For example, the kubelet, kube-proxy, etc. all have REST end-points that are undocumented, and I think developers looking to modify code in these areas are served well by some document that describes the internal non-public REST API. |
|
@derekwaynecarr put that stuff in docs/devel |
bgrant0607
added
the
kind/documentation
|
@derekwaynecarr If you're asking about API documentation, @erictune is correct that the meat should be in docs/devel. For per-call documentation, we're investigating autogeneration: #1052. |
|
Added basic user docs for all moved docs except access.md and security.md. |
|
Copied api/kubernetes.raml documentation into docs/overview.md and updated it. |
|
I've responded to all your comments. I'd encourage you to accept this PR if you think it is a significant improvement, rather than if you think it is perfect. |
|
I'll squash when you say to. |
|
@bgrant0607 PTAL |
| - covers development conventions | ||
| - explains current architecture and project plans | ||
| - **Design Documentation** | ||
| - in [docs/devel](./design) |
|
Very nice! Thanks a lot. A few minor fixes remaining. |
|
Thanks for careful review. All comments addressed in latest push. |
|
Great. LGTM. Please squash. |
Renamed: logging.md -> devel/logging.m Renamed: access.md -> design/access.md Renamed: identifiers.md -> design/identifiers.md Renamed: labels.md -> design/labels.md Renamed: namespaces.md -> design/namespaces.md Renamed: security.md -> design/security.md Renamed: networking.md -> design/networking.md Added abbreviated user user-focused document in place of most moved docs. Added docs/README.md explains how docs are organized. Added short, user-oriented documentation on labels Added a glossary. Fixed up some links.
|
squashed @bgrant0607 |
Separate design and user docs
Moved design documentation into a subdirectory.
Created some new user-focused documentation, and a glossary.
Partially resolves #1813