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 <[email protected]> wrote: > On Tue, Apr 16, 2019 at 08:35:30AM -0700, we recorded a bogon-computron > collision of the <[email protected]> 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 <[email protected]> wrote: > > > > > On Tue, Apr 16, 2019 at 09:20:16AM -0600, we recorded a bogon-computron > > > collision of the <[email protected]> flavor, containing: > > > > On Tue, Apr 16, 2019 at 08:12:45AM -0700, we recorded a > bogon-computron > > > collision of the <[email protected]> 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 > > > [email protected] > > > 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 _______________________________________________ Xastir-dev mailing list [email protected] http://xastir.org/mailman/listinfo/xastir-dev
