[Xastir-dev] Github README

[Curt Mills]

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.

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


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