[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Discuss-gnuradio] PyBOMBS documentation recommendations
From: |
Glen Langston |
Subject: |
Re: [Discuss-gnuradio] PyBOMBS documentation recommendations |
Date: |
Fri, 8 Nov 2019 08:43:10 -0500 |
Thanks for all your documentation efforts!
> On Nov 8, 2019, at 8:27 AM, Müller, Marcus (CEL) <address@hidden> wrote:
>
> Hi Hans,
>
> I like that idea, but revision dates are a central feature of what a
> Wiki like ours offers: you can click on "Versions" and see when the
> current version was last edited.
>
> Sure, that might have just been a typo fix, but whether or not to
> update the "state of" written statement is still as subjective, so I'd
> argue: We've got an automatism for that that's just as good as the
> human hand, so save the time of the human hand :)
> What IS very helpful, especially in the context of installations, is
> stating the platforms and versions of these used: they are not part of
> what a Wiki can automatically track.
I very much agree that the documentation is much more helpful if it
includes a reference to the software revision number that is being
described, along with the OS environment being used.
> Best regards,
> Marcus
>
> On Fri, 2019-11-08 at 13:31 +0800, HansFong wrote:
>> Adding to this, please always add a revision date to any documentation,
>> preferably at the top. It is so difficult to guess if documentation is
>> current or not. Thank you --Hans (BX2ABT)
>>
>> On 11/8/19 11:12 AM, Barry Duggan wrote:
>>> Greetings,
>>>
>>> I have found four URLs giving instructions on using PyBOMBS:
>>> <pre>
>>> https://wiki.gnuradio.org/index.php/InstallingGR#Using_PyBOMBS
>>> https://github.com/gnuradio/pybombs/README.md
>>> https://github.com/gnuradio/gnuradio/README.md
>>> https://www.gnuradio.org/blog/2016-06-19-pybombs-the-what-the-how-and-the-why/
>>>
>>>
>>> </pre>
>>>
>>> In various comments in Discuss-gnuradio, I have concluded that most of
>>> the PyBOMBS users who have failed were due to using old or incomplete
>>> instructions. Also I think that most new users read the
>>> InstallingGR#Using_PyBOMBS instructions only.
>>>
>>> As an advocate of having a single place to document instructions, I
>>> highly recommend picking one site for those instructions, and then
>>> having links to that page from all others. From what I see, the
>>> https://github.com/gnuradio/pybombs/README.md page seems to be the
>>> logical choice since it is revised as PyBOMBS is revised.
>>>
>>> If you choose to have the
>>> https://wiki.gnuradio.org/index.php/InstallingGR#Using_PyBOMBS page
>>> contain the current instructions as well, I can convert the
>>> pybombs/README.md instructions to Mediawiki and put them in
>>> InstallingGR#Using_PyBOMBS.
>>>
>>> Once you have decided what you want done, I can take care of the
>>> edits, if you would like.
>>>
>>> Best regards,