action #60173
openImprove the openQA documentation
0%
Description
The current openQA documentation is imho still lacking in some regards, as I (as a total beginner) am feeling completely lost when I need to get something done in openQA.
My problems with the documentation:
It needs a better introduction that explains the basics, a bit like http://open.qa/docs/#_basic_concepts but with less details (the needle description doesn't belong there, the glossary is just far too long).
It needs comprehensive tutorials for various use cases:
1) I just want to modify a single test, how do I run it?
2) I want to add a new test suite (or a test group, or something that shows up as a single item on o3), how can I do that and what do I need to modify?
3) I want to write actual GUI tests and create new needles, let openQA click things & read stuff from the screen.It is completely intransparent how tests are actually run: there are job groups and test suites. Test suites appear to contain job groups, but how is it decided which tests are run in a job group? E.g. I tried to find out what runs
create_hdd_gnome. But grepping the whole source tree of os-autoinst-distri-opensuse yields 0 hits.At least the openSUSE tests appear to be using a lot of "magic variables" where it is not apparent whether they are required, how they are set and what actually uses them. For example the
REPO_nvariables are automagically set on o3, but not if you start local tests. But your local tests just die if you don't have them set (or maybe it's because of something else, who knows).
My recommendation:
- Get someone fresh (= has never worked with openQA), give them a link to the docs and watch them read. Then after 10-20 minutes ask them whether they have any clue and if not, what's missing. Then try to address that, because most people will give up in far less than 10-20 min.
- Reorder the docs: http://open.qa/docs/#get-testing belongs definitely after http://open.qa/docs/#installing; http://open.qa/docs/#_triggering_tests_based_on_an_any_remote_git_refspec_or_open_github_pull_request is completely buried deep down in the docs and no one knows about it unless told by someone in
#opensuse-factory. - If possible, get a technical writer to help.