Draft ivoatexDoc note

[Mark Taylor]

On Wed, 18 May 2022, Markus Demleitner wrote:

> Hi Mark,
> 
> On Tue, May 17, 2022 at 01:42:28PM +0100, Mark Taylor wrote:
> > On Wed, 11 May 2022, Markus Demleitner wrote:
> > > Now that I think we're doing an acceptable job of describing how to
> > > interact with github as an IVOA contributor, I'd like to publish the
> > > next version of ivoatexDoc; version 1.2 (that's what is currently in
> > > the doc repo) still has a lot of volute content.
> >
> > One thing that could be clarified; the use of git and github is
> > implicit, but the document doesn't say this very explicitly in
> > the obvious places.  I'd suggest namechecking git and/or github
> > in the Section 4 introduction and possibly the section name too,
> > and maybe somewhere in Section 1 as well.
> 
> Hm... I've paged through the document looking for "git", and while I
> found (and removed) another remnant of the subversion days, I didn't
> find text I could immediately improve in terms of making clear what's
> "just git" and what is "github specials".  But then I found the
> github policies ought to mentioned in the abstract, which lead up to
> <https://github.com/ivoa-std/ivoatexDoc/pull/17>.
> 
> If you think that doesn't do the trick: Where would you see the
> greatest need?

What I had in mind was adding a phrase near the start of section 4
something like:

   [This section discusses practices and policies put in place to
    ensure transparent and reproducible processes]
   ... including recommendations for interacting with the github platform.

or maybe changing the title of section 4 to "Developing IVOA Documents
using Github", since that's really what it's about.

Otherwise the casual reader diving in to section 4 might not understand
what's meant by github-specific language such as the terms
"organisation", "repository", "commit" (though, probably they'll
get the idea eventually assuming they know what github is).

But I already approved PR#17, so if you think it's all right as it
stands, that's OK.

Mark

--
Mark Taylor  Astronomical Programmer  Physics, Bristol University, UK
m.b.taylor at bristol.ac.uk          http://www.star.bristol.ac.uk/~mbt/