[Xastir-dev] Github README

[km5vy Tom Russo]

On Tue, Apr 16, 2019 at 08:35:30AM -0700, we recorded a bogon-computron collision of the <curt.we7u at gmail.com> flavor, containing:
> I was thinking about that github:xastir/Xastir page in terms of a
> first-time user: They want instructions for compiling and getting it
> running RIGHT NOW. They don't care about 95% of what's in README there. At
> least that's where my head is at when I'm hunting down a project and
> cloning it.
> 
> I've been to quite a few other Github sites where the README describes what
> the software is/does, then how to get it up and running. Maybe pointers to
> more detailed docs at the end. That's probably how ours should be as well.
> No extra cruft or side discussions.

I agree.  You should go back and read what was in README prior to our 
Git migration.  It was much, much larger, and 99% of it was irrelevant to
a first time user.  Now we're down to 95% irrelevant verbiage.

> Looking at the below link I'm left with questions. They talk more about the
> project than how to get it running RIGHT NOW. Perhaps putting compile/run
> instructions in the earlier part of it and then the project stuff later
> might work?
> 
> https://help.github.com/en/articles/about-readmes

We have a real documentation problem, and not just in README.md.  Not just 
missing quick-start info, but really detailed guidance that is just plain
obsolete.

The many README.* files in the Xastir source tree are generally just collections
of tidbits that have grown almost continually over the course of the project's
history, sometimes simply cutting-and-pasting from half-baked thoughts in 
email chains.  

The Wiki is nice, but it too suffers from bloat as people add the 
specific build commands for a distro-du-jour that are so tied to one particular
release of that distro that they are stale 6 months later and never updated.

A new user, encountering this project for the first time, will not have an
easy time figuring out what to do where.  What we really need to do is get
rid of a lot of the READMEs we have, and make a much more lean set of
guidance, probably on the wiki.

> On Tue, Apr 16, 2019 at 8:24 AM Tom Russo <russo at bogodyn.org> wrote:
> 
> > On Tue, Apr 16, 2019 at 09:20:16AM -0600, we recorded a bogon-computron
> > collision of the <russo at bogodyn.org> flavor, containing:
> > > On Tue, Apr 16, 2019 at 08:12:45AM -0700, we recorded a bogon-computron
> > collision of the <curt.we7u at gmail.com> flavor, containing:
> > > > Looked at the README which displays at xastir/Xastir on Github
> > recently. It
> > > > doesn't say anything about building Xastir. Is it easy to put a link
> > into
> > > > the markdown there to point to the correct document? If not we could
> > put
> > > > some simple build instructions directly into that file with a pointer
> > to
> > > > more detailed instructions.
> > >
> > > The problem with the README is that it is was enormous and bloated, and
> > > was trimmed dramatically when we moved to Github (because it's displayed
> > > on the front page).  I think it really needs to be trimmed down even more
> > > to something that people will actually read.
> > >
> > > There is a reference to README.Getting-Started "for a relatively quick
> > > overview of how to build and use Xastir" and a link to the wiki for
> > > detailed guidance.  How much more does there need to be?
> > >
> > > It is not difficult to make the references to the other documents into
> > > links in markdown.  I'll get it done for that one link right now.
> >
> > I've done this, but now I see the README.Getting-Started is also bloated
> > (over 5000 words) and not even approximately a "relatively quick overview".
> >
> > A real quick-start guide would be good.  Or just point to the wiki and
> > leave
> > it at that.
> >
> > --
> > Tom Russo    KM5VY
> > Tijeras, NM
> >
> >  echo "prpv_a'rfg_cnf_har_cvcr" | sed -e 's/_/ /g' | tr [a-m][n-z]
> > [n-z][a-m]
> >
> > _______________________________________________
> > Xastir-dev mailing list
> > Xastir-dev at lists.xastir.org
> > http://xastir.org/mailman/listinfo/xastir-dev
> >
> 
> 
> -- 
> Curt, WE7U        http://we7u.wetnet.net        http://www.sarguydigital.com

-- 
Tom Russo    KM5VY
Tijeras, NM  

 echo "prpv_a'rfg_cnf_har_cvcr" | sed -e 's/_/ /g' | tr [a-m][n-z] [n-z][a-m]