Documentation Working Group

[tedsuo]

Documentation Working Group

The OpenTracing community is growing rapidly, moving from a tight-knit group of early adopters to a larger group of developers. In order to support this transition, the Documentation Working Group is tasked with codifying the existing knowledge base into proper documentation which can be easily accessed via the OpenTracing website.

Documentation Projects

• Project Overview
• Cross-Language Specification
• Tags
• Language APIs
• OpenTracing CookBook
• Walkthroughs and Tutorials
• FAQ
• Index of Instrumentations
• Guidelines for framework/library maintainers

Responsibilities

• Schedule and attend Documentation Working Group sessions.
• Maintain community guidelines for contributing documentation changes.
• Setup and maintain documentation infrastructure.
• Produce missing documentation.

Initial agenda for Working Group sessions

• What tools should we use for writing and publishing documentation?
• How can we make a Search feature for OT instrumentations, tools, etc
• Assign first round of documentation/writing tasks

Initial Membership

If you are interested in joining this Working Group, please let @tedsuo know or reply below.

[itsderek23]

Would like to help @tedsuo! Thx for kicking this off.

[pritianka-zz]

Same here! Thanks for the kick off.

[griels]

Hi I'm interested in shaping the documentation of the general API and the C/C++ and Python implementations.

[JStickler]

I'm interested in contributing.

[ringerc]

Cannot currently commit to membership but happy to review changes and comment/submit things. Been working on the Jaeger C++ docs and trying to ask clarifying questions on the opentracing c++ docs.

[tiffon]

I'm interested in contributing.

[tedsuo]

Awesome! I'll leave this issue open till the end of the week, and begin organizing on Monday.

[bhs]

LGTM aside from my one comment here.

[bhs]

Seems like the "documentation working group" is something that will always exist (i.e., it's not transitional). This paragraph feels like a great thing for the PR description, but for this actual .md file I'd rather just describe what the doc working group is without referring to the point in time when this paragraph happened to be added to the .md file. E.g., maybe rewrite to be just the following:

The Documentation Working Group codifies and maintains the existing knowledge base as  proper documentation which can be easily discovered via the OpenTracing website.

?

[tedsuo]

I've merged this PR, and the working group is now created! I've invited everyone who responded in this issue to the working group gitter channel, and created a document for brainstorming an agenda. We will discuss meeting formats on gitter and schedule an initial working group session.

Gitter Channel:
https://gitter.im/opentracing/docs

Agenda Proposals:
https://docs.google.com/document/d/1fu5io0cTaBKAy-ykFyiY1EztaKC0Fd7YF9ZB4sB4cpg/

Cheers,
@tedsuo