|
|
@@ -0,0 +1,51 @@
|
|
|
+# Decision for: Change markdown style guide
|
|
|
+
|
|
|
+<!--
|
|
|
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
|
|
|
+Exceptions. See /LICENSE for license information.
|
|
|
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
|
+-->
|
|
|
+
|
|
|
+Proposal accepted on 2020-09-22
|
|
|
+
|
|
|
+Affirming:
|
|
|
+
|
|
|
+- [chandlerc](https://github.com/chandlerc)
|
|
|
+- [geoffromer](https://github.com/geoffromer)
|
|
|
+- [noncombatant](https://github.com/noncombatant)
|
|
|
+- [tituswinters](https://github.com/tituswinters)
|
|
|
+- [zygoloid](https://github.com/zygoloid)
|
|
|
+
|
|
|
+Abstaining:
|
|
|
+
|
|
|
+- [austern](https://github.com/austern)
|
|
|
+- [josh11b](https://github.com/josh11b)
|
|
|
+- [gribozavr](https://github.com/gribozavr)
|
|
|
+
|
|
|
+## Open questions
|
|
|
+
|
|
|
+### Which style guide?
|
|
|
+
|
|
|
+The core team decided to let the Painter choose the style guide to be used. The
|
|
|
+painter selected to continue using the Google documentation markdown style
|
|
|
+guide.
|
|
|
+
|
|
|
+## Rationale
|
|
|
+
|
|
|
+The core team reached consensus that there should be a style guide, but did not
|
|
|
+have a strong preference between the Google style guide and the Microsoft style
|
|
|
+guide. One advantage of the Microsoft style guide is that it is less
|
|
|
+Google-centric, which could contribute somewhat to our community goal. Given the
|
|
|
+level of experience of the core team members with these style guides, it is not
|
|
|
+clear that a well-informed decision could be made. As such, the core team
|
|
|
+decided to leave the decision of the specific style guide up to the Painter.
|
|
|
+
|
|
|
+### Painter rationale
|
|
|
+
|
|
|
+Given the lack of a high level reason to pick one over the other, the painter
|
|
|
+looked at the available tooling for linting against the two options and spoke
|
|
|
+with people who have written substantial developer documentation against both
|
|
|
+style guides. There was no persuasive reason to change from the Google
|
|
|
+documentation style guide at this time. Specific ambiguities or problems with
|
|
|
+that style guide should instead be addressed, if necessary at all, with
|
|
|
+Carbon-specific local rule.
|