1# How to write WebRTC documentation 2 3<?% config.freshness.owner = 'titovartem' %?> 4<?% config.freshness.reviewed = '2021-03-01' %?> 5 6## Audience 7 8Engineers and tech writers who wants to contribute to WebRTC documentation 9 10## Conceptual documentation 11 12Conceptual documentation provides overview of APIs or systems. Examples can 13be threading model of a particular module or data life cycle. Conceptual 14documentation can skip some edge cases in favor of clarity. The main point 15is to impart understanding. 16 17Conceptual documentation often cannot be embedded directly within the source 18code because it usually describes multiple APIs and entites, so the only 19logical place to document such complex behavior is through a separate 20conceptual document. 21 22A concept document needs to be useful to both experts and novices. Moreover, 23it needs to emphasize clarity, so it often needs to sacrifice completeness 24and sometimes strict accuracy. That's not to say a conceptual document should 25intentionally be inaccurate. It just means that is should focus more on common 26usage and leave rare ones or side effects for class/function level comments. 27 28In the WebRTC repo, conceptual documentation is located in `g3doc` subfolders 29of related components. To add a new document for the component `Foo` find a 30`g3doc` subfolder for this component and create a `.md` file there with 31desired documentation. If there is no `g3doc` subfolder, create a new one; 32 33When you want to specify a link from one page to another - use the absolute 34path: 35 36``` 37[My document](/module/g3doc/my_document.md) 38``` 39 40If you are a Googler also please specify an owner, who will be responsible for 41keeping this documentation updated, by adding the next lines at the beginning 42of your `.md` file immediately after page title: 43 44```markdown 45<?\% config.freshness.owner = '<user name>' %?> 46<?\% config.freshness.reviewed = '<last review date in format yyyy-mm-dd>' %?> 47``` 48 49If you want to configure the owner for all pages under a directory, create a 50`g3doc.lua` file in that directory with the content: 51 52```lua 53config = super() 54config.freshness.owner = '<user name>' 55return config 56``` 57 58After the document is ready you should add it into `/g3doc/sitemap.md`, so it 59will be discoverable by others. 60 61### Documentation format 62 63The documentation is written in GitHub Markdown 64([spec](https://github.github.com/gfm/#:~:text=GitHub%20Flavored%20Markdown%2C%20often%20shortened,a%20strict%20superset%20of%20CommonMark.)). 65 66## Class/function level comments 67 68Documentation of specific classes and function APIs and their usage, including 69their purpose, is embedded in the .h files defining that API. See 70[C++ style guide](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md) 71for pointers on how to write API documentatin in .h files. 72