diff --git a/g3doc/how_to_write_documentation.md b/g3doc/how_to_write_documentation.md new file mode 100644 index 0000000000..aa0414cf69 --- /dev/null +++ b/g3doc/how_to_write_documentation.md @@ -0,0 +1,63 @@ +# How to write WebRTC documentation + + + + +## Audience + +Engineers and tech writers who wants to contribute to WebRTC documentation + +## Conceptual documentation + +Conceptual documentation provides overview of APIs or systems. Examples can +be threading model of a particular module or data life cycle. Conceptual +documentation can skip some edge cases in favor of clarity. The main point +is to impart understanding. + +Conceptual documentation often cannot be embedded directly within the source +code because it usually describes multiple APIs and entites, so the only +logical place to document such complex behavior is through a separate +conceptual document. + +A concept document needs to be useful to both experts and novices. Moreover, +it needs to emphasize clarity, so it often needs to sacrifice completeness +and sometimes strict accuracy. That's not to say a conceptual document should +intentionally be inaccurate. It just means that is should focus more on common +usage and leave rare ones or side effects for class/function level comments. + +In the WebRTC repo, conceptual documentation is located in `g3doc` subfolders +of related components. To add a new document for the component `Foo` find a +`g3doc` subfolder for this component and create a `.md` file there with +desired documentation. If there is no `g3doc` subfolder, create a new one +and add `g3doc.lua` file there with following content: + +``` +config = require('/g3doc/g3doc.lua') +return config +``` + +If you are a Googler also please specify an owner, who will be responsible for +keeping this documentation updated, by adding the next lines at the beginning +of your `.md` file immediately after page title: + +``` +' %?> +' %?> +``` + +After the document is ready you should add it into `/g3doc/sitemap.md`, so it +will be visible for others. + +### Documentation format + +The documentation is written in g3doc, which is a markup format derived from +markdown. This is processed by multiple tools, so we recommend using only simple +markup, and previewing the documents in multiple viewers if possible. + +## Class/function level comments + +Documentation of specific classes and function APIs and their usage, inculding +their purpose, is embedded in the .h files defining that API. See +[C++ style guide](https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md) +for pointers on how to write API documentatin in .h files. + diff --git a/g3doc/sitemap.md b/g3doc/sitemap.md index 8fa28be3f2..10034d5343 100644 --- a/g3doc/sitemap.md +++ b/g3doc/sitemap.md @@ -1,6 +1,23 @@ +[Home](/g3doc/index.md) +* How to contribute + * Code + * [Documentation](/g3doc/how_to_write_documentation.md) +* Public C++ API +* Implementation + * Network + * Congestion control and bandwidth estimation + * Audio + * Video + * DataChannel + * PeerConnection + * Desktop capture + * Stats * Testing * Media Quality and performance * PeerConnection Framework * [Video analyzer](/test/pc/e2e/g3doc/default_video_quality_analyzer.md) + * Call framework + * Video codecs test framework * Network emulation * [Implementation](/test/network/g3doc/index.md) + * Performance stats collection