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.

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
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

rodrigc updated this revision to Diff 10361.Nov 19 2015, 9:58 PM
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)
rodrigc added a reviewer: tests.
ngie added a subscriber: ngie.Nov 19 2015, 11:06 PM

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.

ngie added a comment.Nov 19 2015, 11:22 PM

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 accepted this revision.Nov 19 2015, 11:29 PM
ngie added a reviewer: ngie.
This revision is now accepted and ready to land.Nov 19 2015, 11:29 PM
jmmv added a subscriber: jmmv.Nov 20 2015, 2:05 AM
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.

rodrigc added inline comments.Nov 20 2015, 3:16 AM
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 marked an inline comment as done.Nov 20 2015, 3:17 AM
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.