Documentation fixes. (AFLplusplus#5)

mattweingarten · Feb 27, 2020 · 75dcde2 · 75dcde2
1 parent 2e390ba
commit 75dcde2
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 34 deletions.
diff --git a/README.md b/README.md
@@ -1,32 +1,50 @@
 # FuzzBench: Fuzzer Benchmarking As a Service
 
-FuzzBench is a service/framework for benchmarking and comparing fuzzers.
-It is based on the idea that benchmarking fuzzers should be:
-* Painless
-* Accurate
-* Reproducible
+FuzzBench is a free service that evaluates fuzzers on a wide variety of
+real-world benchmarks, at Google scale. The goal of FuzzBench is to make it
+painless to rigorously evaluate fuzzing research and make fuzzing research
+easier for the community to adopt. We invite members of the research community
+to contribute their fuzzers and give us feedback on improving our evaluation
+techniques.
 
 FuzzBench provides:
+
 * An easy API for integrating fuzzers.
-* Benchmarks from real projects, adding an OSS-Fuzz benchmark is a three-line
+* Benchmarks from real-world projects, adding an
+  [OSS-Fuzz](https://github.com/google/oss-fuzz) benchmark is a three-line
   change.
-* Useful reports, with statistical tests to help you understand the significance
-  of results.
+* A reporting library that produces reports with graphs and statistical tests
+  to help you understand the significance of results.
 
-You can use FuzzBench as a service by integrating a fuzzer using [our simple
-guide](https://google.github.io/fuzzbench/getting-started/adding-a-new-fuzzer/).
-After your integration is accepted, we will run a large-scale
-experiment using your fuzzer (e.g. 20 trials, ~24 benchmarks) and generate
-a report comparing your fuzzer to others.
-If you'd like to run FuzzBench on your own, you can use our
-[guide to running an experiment](https://google.github.io/fuzzbench/advanced-topics/running-an-experiment/).
+To participate, submit your fuzzer to run on the FuzzBench platform by following
+[our simple guide](
+https://google.github.io/fuzzbench/getting-started/adding-a-new-fuzzer/).
+After your integration is accepted, we will run a large-scale experiment using
+your fuzzer and generate a report comparing your fuzzer to others.
+See [sample report](https://github.com/google/fuzzbench#sample-report).
 
 ## Overview
 ![FuzzBench Service diagram](docs/images/FuzzBench-service.png)
 
+## Sample Report
+You can view a sample report
+[here](http://www.fuzzbench.com/reports/sample/index.html).
+This report is generated using 10 fuzzers against 24 real-world benchmarks,
+with 20 trials each and over a duration of 24 hours.
+
+When analyzing reports, we recommend:
+* Checking the strengths and weaknesses of a fuzzer against various benchmarks.
+* Looking at aggregate results to understand the overall significance of the
+  result.
+
+Please provide feedback on any inaccuracies and potential improvements (such as
+integration changes, new benchmarks, etc) by opening a GitHub issue
+[here](https://github.com/google/fuzzbench/issues/new).
+
 ## Documentation
 Read our [detailed documentation](https://google.github.io/fuzzbench/) to learn
 how to use FuzzBench.
 
-## Sample Report
-[Report](https://commondatastorage.googleapis.com/fuzzbench-reports/sample/index.html)
+## Contact
+Join our [mailing list](https://groups.google.com/g/fuzzbench-users) for
+discussions and announcements.
diff --git a/docs/getting-started/adding_a_new_benchmark.md b/docs/getting-started/adding_a_new_benchmark.md
@@ -125,3 +125,5 @@ $ export BENCHMARK_NAME=libpng-1.2.56
 $ make build-$FUZZER_NAME-$BENCHMARK_NAME
 $ make run-$FUZZER_NAME-$BENCHMARK_NAME
 ```
+
+If everything works, submit the integration code via a GitHub pull request.
diff --git a/docs/getting-started/adding_a_new_fuzzer.md b/docs/getting-started/adding_a_new_fuzzer.md
@@ -264,6 +264,8 @@ $ make build-$FUZZER_NAME-all
   $ make -j6 build-$FUZZER_NAME-all
   ```
 
+* Run `make run-format` to format your code.
+
 * Run `make run-presubmit` to lint your code and ensure all tests are passing.
 
-* Run `make run-format` to format your code.
+* Submit the integration code in a GitHub pull request.
diff --git a/docs/index.md b/docs/index.md
@@ -9,26 +9,28 @@ has_toc: false
 
 # FuzzBench: Fuzzer Benchmarking As a Service
 
-FuzzBench is a service/framework for benchmarking and comparing fuzzers.
-It is based on the idea that benchmarking fuzzers should be:
-* Painless
-* Accurate
-* Reproducible
+FuzzBench is a free service that evaluates fuzzers on a wide variety of
+real-world benchmarks, at Google scale. The goal of FuzzBench is to make it
+painless to rigorously evaluate fuzzing research and make fuzzing research
+easier for the community to adopt. We invite members of the research community
+to contribute their fuzzers and give us feedback on improving our evaluation
+techniques.
 
 FuzzBench provides:
+
 * An easy API for integrating fuzzers.
-* Benchmarks from real projects, adding an OSS-Fuzz benchmark is a three-line
+* Benchmarks from real-world projects, adding an
+  [OSS-Fuzz](https://github.com/google/oss-fuzz) benchmark is a three-line
   change.
-* Useful reports, with statistical tests to help you understand the significance
-  of results.
+* A reporting library that produces reports with graphs and statistical tests
+  to help you understand the significance of results.
 
-You can use FuzzBench as a service by integrating a fuzzer using [our simple
-guide]({{ site.baseurl }}/getting-started/adding-a-new-fuzzer/).
-After your integration is accepted, FuzzBench will run a large-scale
-experiment using your fuzzer (e.g. 20 trials, ~24 benchmarks) and generate
-a report comparing your fuzzer to other fuzzers.
-If you'd like to run FuzzBench on your own, you can use our
-[guide to running an experiment]({{ site.baseurl }}/advanced-topics/running-an-experiment/).
+To participate, submit your fuzzer to run on the FuzzBench platform by following
+[our simple guide](
+https://google.github.io/fuzzbench/getting-started/adding-a-new-fuzzer/).
+After your integration is accepted, we will run a large-scale experiment using
+your fuzzer and generate a report comparing your fuzzer to others.
+See [sample report](https://github.com/google/fuzzbench#sample-report).
 
 ## Overview
 
@@ -43,6 +45,25 @@ fuzzer with FuzzBench.
 fuzzers both on individual benchmarks and in aggregate.
 
 ## Sample Report
+You can view a sample report
+[here](http://www.fuzzbench.com/reports/sample/index.html).
+This report is generated using 10 fuzzers against 24 real-world benchmarks,
+with 20 trials each and over a duration of 24 hours.
+
+When analyzing reports, we recommend:
+* Checking the strengths and weaknesses of a fuzzer against various benchmarks.
+* Looking at aggregate results to understand the overall significance of the
+  result.
+
+Please provide feedback on any inaccuracies and potential improvements (such as
+integration changes, new benchmarks, etc) by opening a GitHub issue
+[here](https://github.com/google/fuzzbench/issues/new).
+
+## Documentation
+Read our [detailed documentation](https://google.github.io/fuzzbench/) to learn
+how to use FuzzBench.
 
-[Report](https://commondatastorage.googleapis.com/fuzzbench-reports/sample/index.html)
+## Contact
+Join our [mailing list](https://groups.google.com/g/fuzzbench-users) for
+discussions and announcements.