Guidelines for writing documentation

[krnowak]

Currently we have three places where we can put documentation:

• opentelemetry.io website
• README.md of every go module
• package documentation (usually in doc.go)

I think we need to find out what kind of documentation we have (API docs, guides, contribution guidelines, project-wide information, …), what are the targets of the documentation (contributors, instrumentation developers, application developers, …) and decide where each kind of docs should be put. Currently there is a quickstart guide on the website, but also there are some "quickstart guide" like docs for the exporters in READMEs.

This is a bit of a mess that can easily lead to duplication.

I suppose that the result of resolving this issue would be a document with guidelines for writing documentation for otel-go.

[leewei05]

@krnowak Hi, I'm Lee. I want to contribute to open-telementry by writing documentation.
Is there anything I can do to help resolving this issue? :)

[MrAlias]

@leewei05 I would hold off on taking this issues as it isn't so much about writing documentation as it is restructuring and defining where documentation is kept.

From the SIG meeting today:

• README.md should be a high-level developer centric source of information. It should contain what new developers using OTel or wanting to contribute to this project need to know. This will likely include a lot of linking.
• The opentelemetry.io website should be hold the "quickstart" type guides. This has the benefit of being HTML that can be linked or embedded and will likely be the entry point for new users of OTel. Any code in these docs needs to be versioned so new users pulling the default branch are not left with a broken example. Additionally, our local developer docs (maybe the release process guide?) need to have a step to keep things in sync.
• The Go docs (e.g. package, type, func) need to contain information for developers using the code. All examples should be kept as example tests. That way the code will be verified that it compiles and properly rendered on the Go docs site.