ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gintautas Grigelionis <g.grigelio...@gmail.com>
Subject Re: Ant documentation
Date Fri, 02 Mar 2018 09:39:45 GMT
2018-03-02 9:54 GMT+01:00 Stefan Bodewig <bodewig@apache.org>:

> On 2018-03-01, Stefan Bodewig wrote:
>
> >> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
> >> g.grigelionis@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>&lt;...&gt;</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 ;-)

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message