search

owasp-amass / amass

In-depth attack surface mapping and asset discovery
https://owasp.org/www-project-amass/
Other
11.63k stars 1.85k forks source link

Initial version of Amass 4 quick start guide. #974

Open garthoid opened 10 months ago

garthoid commented 9 months ago

Please review and provide next steps if required.

thornshadow99 commented 9 months ago

Hi there, I am a technical writer and was told about this by baltimorty on Discord, so I did an edit. It seemed a bit too casual--too much "I" and "you"--so I tightened that up, especially in the Wrap Up. Overall, it seemed fine with only three major flaws.

Flaw 1: It states that Amass 4 has a major change (the OAM) but it does not spend any time explaining what the OAM is or how the architecture has changed to fit it. The only explanation of the OAM is in the repositories section and that explanation is very vague. If the OAM is brand new, it needs at least one paragraph to explain or links to webpages that can give more detail.

Flaw 2: The instructions require Docker to operate and the author does not really explain why except that it's "a great addition to our modern lifestyle"? They should really add more about the decision to use Docker other than a whim. If other options are available, shouldn't the author provide installation information for those options? Just a thought.

Flaw 3: The note that begins with "Here (and this is important as I missed this before)" is problematic because it undermines the confidence of the reader in the document. It should not be written that way. The author should either put that information in the place where it belongs or leave it there without that parenthetical expression or the other related text. I got rid of all the problematic text (including the stuff about the "rabbithole").

Since I am new to GitHub and I am not sure that I can branch anything, the edited version is attached below. It is in PDF because GitHub on the browser did not recognize my text file.

Rob Thornton thornshadow99 amass quick guide edit.pdf

kingthorin commented 5 months ago

It'd be nice if this got merged. It doesn't have to be perfect on the first go around, it can always be tweaked over time. Also trying to compare vs. a PDF does not seem like a handy contributor experience.