Page MenuHomeFreeBSD

Add quick steps for running kyua tests to README. Install the README in /usr/tests.
ClosedPublic

Authored by rodrigc on Nov 19 2015, 9:58 PM.
Tags
Referenced Files
Unknown Object (File)
Apr 17 2017, 10:15 PM
Unknown Object (File)
Apr 13 2017, 8:27 AM
Unknown Object (File)
Apr 13 2017, 2:42 AM
Unknown Object (File)
Apr 11 2017, 2:25 PM
Unknown Object (File)
Apr 9 2017, 8:44 AM
Unknown Object (File)
Mar 22 2017, 7:22 PM
Unknown Object (File)
Mar 20 2017, 8:23 PM
Unknown Object (File)
Jan 26 2017, 6:48 AM
Subscribers

Details

Reviewers
ngie
Group Reviewers
tests
Commits
rS291089: Copy README into /usr/tests
Summary

I have fielded many questions from people who see /usr/tests
on their system but do not know how to run the tests.
Throw these people a breadcrumb by putting this information
at the top of the README file, and then install the README in
/usr/tests.

Test Plan

make install

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

rodrigc retitled this revision from to Add quick steps for running kyua tests to README. Install the README in /usr/tests..
rodrigc updated this object.
rodrigc edited the test plan for this revision. (Show Details)

It seems like this should be installed to /usr/share/docs

No, I don't want this in `/usr/share/docs`. This is meant to be *newbie* friendly so people can just go in /usr/tests
and figure out what to do relatively quickly by looking at the README.
The way to figure this out right now is confusing enough as it is with info scattered all over the place in different man pages,
wikis, etc. The end result is that newbies can't figure out what to do, and keep asking me.

No, I don't want this in `/usr/share/docs`. This is meant to be *newbie* friendly so people can just go in /usr/tests
and figure out what to do relatively quickly by looking at the README.
The way to figure this out right now is confusing enough as it is with info scattered all over the place in different man pages,
wikis, etc. The end result is that newbies can't figure out what to do, and keep asking me.

I understand where you're coming from. It just gets to be a bit of a chicken and egg problem, i.e. how will they know where to look for the README file if they don't know about /usr/tests?

They already see it, they just don't know what to do once they are there.

ngie added a reviewer: ngie.
This revision is now accepted and ready to land.Nov 19 2015, 11:29 PM
jmmv added inline comments.
tests/README
4 ↗(On Diff #10361)

Two headings of the same level, one immediately after the other, look really ugly. Consider removing this one.

11 ↗(On Diff #10361)

Why not just refer people to tests(7) and rely on the properly formatted manual page? These instructions are redundant and will need extra maintenance.

If the manpage is unsuitable as it is, change it. Add a new section at the very top saying "Quickstart guide" or something like that.

The same applies for all the text below. The documentation belongs in the tests(7) manual page. I think it's OK for a README to exist here and provide brief pointers to the page, but the real contents should be there. If the current page has navigation issues, that's a different story, but they can certainly be addressed.

tests/README
11 ↗(On Diff #10361)

README and tests(7) in their current form are way to wordy. In tests(7), I need to scroll through nearly 50 lines of text before
there is one sentence describing how to run the tests.

A lot of tests(7) reflects your personal opinions of when and how to run tests. Those kind of opinions belong on
your personal blog not in the man page.

The kind of newbies we want to run the tests are not going to have the patience to read through all this stuff.
I'm not sure how open you are to having the content in these documents trimmed.

rodrigc added inline comments.
tests/README
4 ↗(On Diff #10361)

OK

This revision was automatically updated to reflect the committed changes.
rodrigc marked an inline comment as done.