2018-03-02 9:54 GMT+01:00 Stefan Bodewig <bode...@apache.org>: > On 2018-03-01, Stefan Bodewig wrote: > > >> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis < > >> g.grigelio...@gmail.com> wrote: > > >>> I tried then to use the replacement tags as consistently as possible in > >>> such a large body of text, but I realised that we perhaps need a kind > of a > >>> style guide. Would you like to discuss it? Where would it best fit in > the > >>> source code tree? > > > I'm not convinced I want to have any kind of rules keep people from > > writing docs :-) > > This comment isn't fair and I should have known better, sorry. > > Whenever people who are new to Open Source ask where to contribute I > first point out that it is supposed to be fun and they should pick the > thing they enjoy most. > > For most developers I know (including myself) writing documentation is > not something they enjoy. It's a chore that needs to get done. Having a > style guide can help or it can make things worse. If it provides a > guideline that makes it easier to write proper documentation, then it > probably is a welcome tool. What I wouldn't want to see is a set of > rules that get enforced and may even prevent people from writing > documentation - but I don't think this is what Gintas suggested. > > And of course there are the rare folks who actually enjoy writing > docs. All power to them :-) >
I didn't even notice your remark, really :-) All I wanted to say, keeping things visually consistent helps understanding. So, my simple set of rules is: - <var> is for attributes - <q> is for values - <code> is for shell variable names/property name/CLI options and input (should change that to <kbd>, really) - <samp> is for everything else, like filenames etc I was thinking of finding a suitable tag to overload in order to avoid typing <code><...></code>; but I'd settle for a CSS class and/or CSS selector for q as a child of code (because it's a special case of quoting, really). So, any opinions on that? Gintas P.S. I was having a beer tonight with a guy who told me that he liked Gradle, but the documentation was lacking ;-)
