Documentation overhaul

[tsenart]

Documentation overhaul

Vegeta's documentation today is OK, but it can be substantially improved. This issue is meant to track ideas and needs for better documentation.

examples/ directory

All common (or not so common) recipes and examples ought to be captured in an appropriately named file in the examples/ directory, be they CLI or library related.

The README should be reduced then and prominently reference this examples/ directory.

Manpages

The README is currently serving as the home for all documentation types. Its structure is hard to navigate and find what you need as new user. Documenting the flags and behavior of the CLI ought to be done in manpages, shipped with OS specific packages, possibly linked from the README to an online representation of them integrated in the documentation site.

Documentation site

Visually appealing, user friendly documentation for beginners and experts alike. Easy to find answers. Clearly articulated value proposition of the project, its origins, its user base and its governance.

Inspiration

• https://paw.cloud/docs/

Recipes and use cases (jobs to be done)

• Distributed attacks
• Terminal plotting integrations
• Data analysis guides
• Dynamic attacks via library use with changing parameters (rate, targets, etc)
• Dynamic attacks via command line utility composition and some shell scripting

[daluu]

What would we do for web docs? API or help docs hosted on a site like JavaDocs, python docs, or go doc? Or make use of the GH wiki feature? Or more *.md files in the repo that are not README?

[tsenart]

I'm thinking the web docs would contain step-by-step guides, recipes and other chunks of common uses of Vegeta, explained and articulated. As for how to publish it, this looks great: https://github.com/squidfunk/mkdocs-material. We'd do it on Github Pages.

The same recipes and examples, however, ought to be added to the examples/ directory, be they CLI or library examples. For each common or not so common use case, an example file ought to be there, named appropriately.

Then the README should prominently reference both these examples/ dir and the web docs. GoDoc itself also integrates well with such directory for Go code.

I think we should start with the examples/ directory and when that's done focus on the web docs.