No announcement yet.

Documentation Improvement proposal

  • Filter
  • Time
  • Show
Clear All
new posts

  • Documentation Improvement proposal

    I've been reading the whole pdf file about the phoronix test suite, and i find something is missing.

    I mean, surely someone can start doing tests just for fun and reverse engineer some processes, but here's my two cents on how to improve in the phoronix documentation:
    1. Add a "howto" section: basic test execution, and explain messages and questions.

    For example, i get asked:

        Would you like to save these test results (Y/n): y
        Enter a name to save these results under: dobby-pybench
        Enter a unique name to describe this test run / configuration: dobby
    But what does the question mean? The third question seems actually redundant, but i know it isn't, and I think someone should explain somewhere what does question refer to, and what are they going to influence. That's probably going to be just obvious for original authors, but it isn't for casual users or novices (like me, for example).
    1. What files are produced? And where? What formats? How to parse/use them?

    I think it's important to state clearly what files is PTS going to write, where will they be located and how to parse/use them later.

    Example: i ran a test. Where should I look for results?

    Say i want to compare result for a certain test on machine A with results for the same test on machine B. How do i do that?

    Why isn't that explained anywhere?

    Say that one month later i get a new machine and want to recall machine A and B results, run the same test and compare results, how to do that ?

    I think practical explanation on how to do things would be appreciated.

  • #2 and the HTML/PDF documentation should cover most basic usage. But yes, I would love to improve the PTS documentation, but unfortunately don't have the resources to do so at the moment. With driving 99% of the PTS development myself on top of all my other roles, I don't have much extra time to devote to other tasks. So unless there's a corporate customer requesting it or someone wanting to sponsor the work or donate to the cause or help in the documentation process, it will be a slow process
    Michael Larabel