Add OpenTelemetry API package layout

specification/package-layout.md

@@ -0,0 +1,56 @@
+# OpenTelemetry Project Package Layout
+This documentation serves to document the "look and feel" of a basic layout for OpenTelemetry projects. This package layout is intentionally generic and it doesn't try to impose a language specific package structure.
+
+## API Package
+Here is a proposed generic package structure for Public API package.
+
+### `/metrics`
+
+This directory describes the Metrics API that can be used to record application Metrics.
+
+### `/resources`
+
+This API for resource information population.
+
+The resource directory primarily defines a type [Resource](../terminology.md#resources) that captures information about the entity for which stats or traces are recorded. For example, metrics exposed by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod, and container name.
+
+### `/distributedcontext`
+
+This directory describes the DistributedContext API that can be used to manage metrics-related labeling.
+
+This API consists of a few main classes:
+
+- `Entry` is used to label anything that is associated with a specific operation, such as an HTTP request.
+- An `Entry` consists of `EntryMetadata`, `EntryKey`, and `EntryValue`.
+
+### `/trace`
+
+This API consist of a few main classes:
+
+- `Tracer` is used for all operations. See [Tracer](./tracing-api.md#tracer) section.
+- `Span` is a mutable object storing information about the current operation
+   execution. See [Span](./tracing-api.md#span) section.
+- `SpanData` is an immutable object that is used to report out-of-band completed
+  spans. See [SpanData](./tracing-api.md#spandata) section.
+
+### `/internal` (_Optional_)
+Private application and library code.
+
+### `/log` (_In the future_)
+> TODO: log operations
+
+
+A typical top-level directory layout:
+```
+api
+   ├── metrics
+   ├── resources
+   ├── trace
+   │   ├── propagation # headers that are the public API for trace propagation, using different encodings.
+   │   └── samplers    # is used to make decisions on `Span` sampling.
+   ├── distributedcontext
+   │   └── propagation
+   ├── internal
+   └── log
+```
+> Use lowercase or CamelCase or Snake Case (stylized as snake_case) depends on the language.