[Xastir-dev] Github README

Tue Apr 16 08:52:45 PDT 2019

Works for me. Thanks for making that tweak this morning, definitely better.
Also thanks for the earlier trim-down of the README.md.

On Tue, Apr 16, 2019 at 8:48 AM km5vy Tom Russo <russo at bogodyn.org> wrote:

> 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]
>
>

-- 
Curt, WE7U        http://we7u.wetnet.net        http://www.sarguydigital.com