After some discussions about how things get documented and maintained (or not) at 18F, @tbaxter-18f and some others came up with a rough framework for how to most usefully document our opinions, guidelines, and decisions. One of the points of conversation included the idea that sets of opinions are less valuable than explanations of why we recommend the things we recommend, how to evaluate future tooling, and how to prevent one voice from owning an entire set of documents.
The front end guide seems like a good place to try these guidelines out and see if it gives us something that is more valuable than what we've got. The current form is almost impossible to maintain properly, especially given the fluctuations in the number of front end developers at 18F. Rather than devote several entire pages to "how to write your CSS," what if it became a tool for deciding how to write CSS yourself? What if we focused on tools that people could use even as technology changes, without having to update the documentation every time a new framework comes in vogue?
This is an experiment to see what such a rewrite would entail, and, as such, I'd love feedback and conversation around it.
After some discussions about how things get documented and maintained (or not) at 18F, @tbaxter-18f and some others came up with a rough framework for how to most usefully document our opinions, guidelines, and decisions. One of the points of conversation included the idea that sets of opinions are less valuable than explanations of why we recommend the things we recommend, how to evaluate future tooling, and how to prevent one voice from owning an entire set of documents.
The front end guide seems like a good place to try these guidelines out and see if it gives us something that is more valuable than what we've got. The current form is almost impossible to maintain properly, especially given the fluctuations in the number of front end developers at 18F. Rather than devote several entire pages to "how to write your CSS," what if it became a tool for deciding how to write CSS yourself? What if we focused on tools that people could use even as technology changes, without having to update the documentation every time a new framework comes in vogue?
This is an experiment to see what such a rewrite would entail, and, as such, I'd love feedback and conversation around it.