search

projectcalico / calico

Cloud native networking and network security
https://docs.tigera.io/calico/latest/about/
Apache License 2.0
6.02k stars 1.34k forks source link

Configuration info is too scattered across docs #30

Closed fasaxc closed 6 years ago

fasaxc commented 8 years ago

The configuration page currently talks about system and Felix configuration but it doesn't talk about calicoctl or how to set config values.

I think we should have a landing page that gives an overview of the different types of configuration we support and why you'd want to tweak each of them (System requirements; Felix; BGP; integration-specific) and fans people out to more detailed docs.

ozdanborne commented 7 years ago

I went through the docs and put together a list of all the current config docs we have:

Location Purpose
/usage/configuration Felix & Openstack
/usage/configuration/securing-calico Weirdly redundant general calico security info that probably shouldn't exist
/usage/configuration/bgp Using calicoctl to configure bgp
/usage/configuration/as-service How to configure / use calico/node with systemd
/reference/cni-plugin/configuration CNI config reference
/reference/policy-controller/configuration Policy-controller config reference
/reference/calicoctl/commands/config calicoctl config command reference

Seems the approach we've taken is:

I actually like this approach, and think with a little cleanup we could further enforce it. I propose the following actions:

Sound like a good increment?

caseydavenport commented 7 years ago

@djosborne that sounds about right to me.

The usage section shouldn't have configuration references in it. Those should all go in the reference section.

ozdanborne commented 7 years ago

My above comment on moving configuration sections was mostly fixed by #505

ozdanborne commented 7 years ago

Actually, I'm going to reopen this. I think we could still use a /usage/configuration/index overview page which is basically a page of links to all the places where configuration info is detailed.

caseydavenport commented 7 years ago

We need to have a clear idea of what sorts of documentation goes in each top-level section. Here's how I've been thinking about it to-date. I think this is largely correct, but feel free to contradict me :)

Getting Started

This should be where new users go. It includes quick-start guides, some basic tutorials to show off Calico's capabilities, and links to more advanced topics once users are comfortable with the basics.

Each orchestrator has a landing page that is targeted at people who are coming to see Calico for the first time. It's a transition from the "marketing" type material (why is Calico great) to some quick commands people can run to see it firsthand, and then funnels people off to the usage section for more details.

Usage

These should all be docs that are a "verb". They should be task focused, each doc containing a goal and a set of steps you can follow to achieve it. They should not be detailed description of components or tabulated configuration information.

Examples:

Reference

These docs are the complete reference for Calico. If there's a configuration option you're looking for, it goes here in one of the per-component references. Not every option has a "how to" guide, but has enough description.

Examples:

tmjd commented 7 years ago

I think that is great info Casey so I added it to the docs README here #597. One question I have is where should we put stuff like:

caseydavenport commented 7 years ago

Good questions!

what does IP-in-IP do

This feels like it would fit in the reference section, if we want to document it at all. Details about "what is IPIP" aren't necessarily right for our docs.

why would someone enable IP-in-IP?

This is probably in a few places. Each "Usage" guide should start with a clear "This is why you want to do this" type statement to make it clear to a user if the guide is relevant to them.

Caveats when using a feature

This probably goes with the reference documentation for that feature, I think. It may also be covered in troubleshooting / FAQ type docs in usage?

tmjd commented 7 years ago

what does IP-in-IP do

Agreed we shouldn't be explaining generically what IP-in-IP is (though it wouldn't hurt to have a link to somewhere that does, if we don't already) but I would think there should be some kind of explanation of how it changes things. Kind of similar to Caveats I guess. Context: I was looking at https://github.com/projectcalico/calicoctl/issues/1296 and think the docs should reflect how IP-in-IP changes things. Specifically if you don't have IP-in-IP a workload and host endpoint can communicate but if it is enabled then they cannot (without nat-outgoing but that causes other changes).

tmjd commented 7 years ago

@caseydavenport do you think additional reorganization needs to be done under this issue or simply creating the /usage/configuration/index landing page that djosborne mentioned?

tmjd commented 7 years ago

At this point I think the biggest improvements will be adding the a landing page and some of the missing common tasks to the Usage section #778.

I think it makes sense to move some of the configuration in the Reference section into new configuration pages that should be created in Usage but I think that would be mostly just for calicoctl. Probably with the creation of an Installation and configuration page #632.

ozdanborne commented 7 years ago

@tmjd What needs to be done to close this issue out? If it's just adding a toplevel config landing page, can we open that as a new issue and close this larger one out?

tmjd commented 7 years ago

@ozdanborne Yes I think that is all that is needed is a landing page to close out this issue. As I mentioned in my previous comment there might be some rearranging that can be done when the calicoctl usage page is created but I just went and commented on that issue with that thought.

I think we should have landing page for Usage, do you think we should have a separate landing page for the configuration portion of Usage too?