diff --git a/docs/reference/operator_parameters.md b/docs/reference/operator_parameters.md
index 76109c890..60416e818 100644
--- a/docs/reference/operator_parameters.md
+++ b/docs/reference/operator_parameters.md
@@ -290,12 +290,12 @@ In the CRD-based configuration they are grouped under the `load_balancer` key.
   replaced with the hosted zone (the value of the `db_hosted_zone` parameter).
   No other placeholders are allowed.
 
-## AWS or GSC interaction
+## AWS or GCP interaction
 
 The options in this group configure operator interactions with non-Kubernetes
-objects from AWS or Google cloud. They have no effect unless you are using
+objects from Amazon Web Services (AWS) or Google Cloud Platform (GCP). They have no effect unless you are using
 either. In the CRD-based configuration those options are grouped under the
-`aws_or_gcp` key.
+`aws_or_gcp` key. Note the GCP integration is not yet officially supported.
 
 * **wal_s3_bucket**
   S3 bucket to use for shipping WAL segments with WAL-E. A bucket has to be
diff --git a/pkg/apis/acid.zalan.do/v1/crds.go b/pkg/apis/acid.zalan.do/v1/crds.go
index ec25d722f..5f1704527 100644
--- a/pkg/apis/acid.zalan.do/v1/crds.go
+++ b/pkg/apis/acid.zalan.do/v1/crds.go
@@ -6,7 +6,7 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// CRDResource
+// CRDResource* define names necesssary for the k8s CRD API
 const (
 	PostgresCRDResourceKind   = "postgresql"
 	PostgresCRDResourcePlural = "postgresqls"
diff --git a/pkg/apis/acid.zalan.do/v1/operator_configuration_type.go b/pkg/apis/acid.zalan.do/v1/operator_configuration_type.go
index e168a25ad..f7b0d76cb 100644
--- a/pkg/apis/acid.zalan.do/v1/operator_configuration_type.go
+++ b/pkg/apis/acid.zalan.do/v1/operator_configuration_type.go
@@ -14,7 +14,7 @@ import (
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// OperatorConfiguration defines the specification for the OperatorConfigration.
+// OperatorConfiguration defines the specification for the OperatorConfiguration.
 type OperatorConfiguration struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata"`
@@ -24,7 +24,7 @@ type OperatorConfiguration struct {
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// OperatorConfigurationList defines the list of the OperatorConfigration.
+// OperatorConfigurationList is used in the k8s API calls
 type OperatorConfigurationList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata"`
@@ -32,13 +32,13 @@ type OperatorConfigurationList struct {
 	Items []OperatorConfiguration `json:"items"`
 }
 
-// PostgresUsersConfiguration defines the user of the Postgres.
+// PostgresUsersConfiguration defines the system users of Postgres.
 type PostgresUsersConfiguration struct {
 	SuperUsername       string `json:"super_username,omitempty"`
 	ReplicationUsername string `json:"replication_username,omitempty"`
 }
 
-// KubernetesMetaConfiguration defines the pod service account info
+// KubernetesMetaConfiguration defines k8s conf required for all Postgres clusters and the operator itself
 type KubernetesMetaConfiguration struct {
 	PodServiceAccountName string `json:"pod_service_account_name,omitempty"`
 	// TODO: change it to the proper json
@@ -79,7 +79,7 @@ type OperatorTimeouts struct {
 	ReadyWaitTimeout       Duration `json:"ready_wait_timeout,omitempty"`
 }
 
-// LoadBalancerConfiguration defines the LB DNS configration
+// LoadBalancerConfiguration defines the LB configuration
 type LoadBalancerConfiguration struct {
 	DbHostedZone              string                `json:"db_hosted_zone,omitempty"`
 	EnableMasterLoadBalancer  bool                  `json:"enable_master_load_balancer,omitempty"`
@@ -88,7 +88,8 @@ type LoadBalancerConfiguration struct {
 	ReplicaDNSNameFormat      config.StringTemplate `json:"replica_dns_name_format,omitempty"`
 }
 
-//AWSGCPConfiguration defines the configration of AWS s3
+// AWSGCPConfiguration defines the configuration for AWS
+// TODO complete Google Cloud Platform (GCP) configuration
 type AWSGCPConfiguration struct {
 	WALES3Bucket string `json:"wal_s3_bucket,omitempty"`
 	AWSRegion    string `json:"aws_region,omitempty"`
@@ -163,5 +164,5 @@ type OperatorConfigurationUsers struct {
 	TeamAPIRoleConfiguration map[string]string `json:"team_api_role_configuration,omitempty"`
 }
 
-//Duration is time.Duration
+//Duration shortens this frequently used name
 type Duration time.Duration
diff --git a/pkg/apis/acid.zalan.do/v1/register.go b/pkg/apis/acid.zalan.do/v1/register.go
index f4f9a250a..c47d9f8ff 100644
--- a/pkg/apis/acid.zalan.do/v1/register.go
+++ b/pkg/apis/acid.zalan.do/v1/register.go
@@ -8,7 +8,7 @@ import (
 	"github.com/zalando-incubator/postgres-operator/pkg/apis/acid.zalan.do"
 )
 
-// APIVersion refered API version
+// APIVersion of the `postgresql` and `operator` CRDs
 const (
 	APIVersion = "v1"
 )
diff --git a/pkg/apis/acid.zalan.do/v1/util.go b/pkg/apis/acid.zalan.do/v1/util.go
index ce3843f40..dee72fe4e 100644
--- a/pkg/apis/acid.zalan.do/v1/util.go
+++ b/pkg/apis/acid.zalan.do/v1/util.go
@@ -14,7 +14,7 @@ var (
 	serviceNameRegex = regexp.MustCompile(serviceNameRegexString)
 )
 
-// Clone returns Postgresql.DeepCopy
+// Clone convenience wrapper around DeepCopy
 func (p *Postgresql) Clone() *Postgresql {
 	if p == nil {
 		return nil
@@ -84,7 +84,7 @@ func validateCloneClusterDescription(clone *CloneDescription) error {
 	return nil
 }
 
-// Success returns status ClusterFailed or not
+// Success of the last operation on a Postgres cluster
 func (status PostgresStatus) Success() bool {
 	return status != ClusterStatusAddFailed &&
 		status != ClusterStatusUpdateFailed &&
diff --git a/pkg/cluster/types.go b/pkg/cluster/types.go
index 7f52778f6..b283e652b 100644
--- a/pkg/cluster/types.go
+++ b/pkg/cluster/types.go
@@ -1,12 +1,13 @@
 package cluster
 
 import (
+	"time"
+
 	acidv1 "github.com/zalando-incubator/postgres-operator/pkg/apis/acid.zalan.do/v1"
 	"k8s.io/api/apps/v1beta1"
 	"k8s.io/api/core/v1"
 	policybeta1 "k8s.io/api/policy/v1beta1"
 	"k8s.io/apimachinery/pkg/types"
-	"time"
 )
 
 // PostgresRole describes role of the node
@@ -20,7 +21,7 @@ const (
 	Replica PostgresRole = "replica"
 )
 
-// PodEventType describe value of event type
+// PodEventType describes value of event type
 type PodEventType string
 
 // Possible values for the EventType
diff --git a/pkg/cluster/util.go b/pkg/cluster/util.go
index 8b5a867c2..f6e2ff096 100644
--- a/pkg/cluster/util.go
+++ b/pkg/cluster/util.go
@@ -460,7 +460,7 @@ func (c *Cluster) setSpec(newSpec *acidv1.Postgresql) {
 	c.specMu.Unlock()
 }
 
-// GetSpec returns cluster.Postgresql
+// GetSpec returns a copy of the operator-side spec of a Postgres cluster in a thread-safe manner
 func (c *Cluster) GetSpec() (*acidv1.Postgresql, error) {
 	c.specMu.RLock()
 	defer c.specMu.RUnlock()
diff --git a/pkg/spec/types.go b/pkg/spec/types.go
index 360fd580d..c9da79297 100644
--- a/pkg/spec/types.go
+++ b/pkg/spec/types.go
@@ -125,7 +125,7 @@ func (n *NamespacedName) Decode(value string) error {
 	return n.DecodeWorker(value, GetOperatorNamespace())
 }
 
-// UnmarshalJSON covert to NamespacedName from byte slice
+// UnmarshalJSON converts a byte slice to NamespacedName
 func (n *NamespacedName) UnmarshalJSON(data []byte) error {
 	result := NamespacedName{}
 	var tmp string
diff --git a/pkg/util/config/util.go b/pkg/util/config/util.go
index 894f087d2..4c1bdf7e0 100644
--- a/pkg/util/config/util.go
+++ b/pkg/util/config/util.go
@@ -19,7 +19,7 @@ type fieldInfo struct {
 	Field   reflect.Value
 }
 
-// StringTemplate is string
+// StringTemplate is a convenience alias
 type StringTemplate string
 
 func decoderFrom(field reflect.Value) (d decoder) {
@@ -240,7 +240,7 @@ func (f *StringTemplate) Format(a ...string) string {
 	return res
 }
 
-// MarshalJSON returns json.Marshal(byte slice) from StringTemplate
+// MarshalJSON converts a StringTemplate to byte slice
 func (f StringTemplate) MarshalJSON() ([]byte, error) {
 	return json.Marshal(string(f))
 }
diff --git a/pkg/util/teams/teams.go b/pkg/util/teams/teams.go
index f51ccbc94..d7413ab9c 100644
--- a/pkg/util/teams/teams.go
+++ b/pkg/util/teams/teams.go
@@ -43,7 +43,7 @@ type httpClient interface {
 	Do(req *http.Request) (*http.Response, error)
 }
 
-// Interface have to implement TeamInfo
+// Interface to the TeamsAPIClient
 type Interface interface {
 	TeamInfo(teamID, token string) (tm *Team, err error)
 }