22
33### Contributing
44
5- The Developer Guide needs to be updated for the modern security landscape,
6- and OWASP is reviving this project to do just that.
7- The project has a team of leaders that will oversee the project
8- and now we need as many members of the security community as possible to contribute.
5+ The Developer Guide has been updated for the modern security landscape,
6+ concentrating less on covering everything in one document and more on introducing a subject/project
7+ and then suggesting where more in-depth information can be found.
8+ The project has a team of leaders that oversee the project
9+ and contributions from members of the security community are positively encouraged.
910
1011All contributions and suggestions are certainly welcome, and we ask that
1112you follow the [ contributing code of conduct] [ conduct ] .
@@ -38,13 +39,13 @@ and keeps track of progress towards each milestone.
3839### Style Guide
3940
4041The Developer Guide will have many contributors, and it is an aim to keep the style of writing similar throughout.
41- It would be good to keep to a style used in OWASP flagship projects [ ASVS] [ asvs ] and [ WSTG] [ wstg ] ,
42+ Follow the style used in OWASP flagship projects [ ASVS] [ asvs ] and [ WSTG] [ wstg ] ,
4243which is speaking from first person plural and semi-formal in tone.
4344
4445### Technical level
4546
4647Generally the guide is aimed at the introductory to medium technical levels,
47- and should rarely deal with a subject at an advanced level.
48+ and should rarely deal with any subject at an advanced level.
4849This is a deliberate policy that makes the guide accessible and keeps the length reasonable.
4950
5051The overview/introduction of the main sections should be aimed at the introductory level,
@@ -54,13 +55,24 @@ instead provide links to these specialist security knowledge bases.
5455
5556### Page structure
5657
57- Each sub-section should deal with one specific subject, for example 'Threat modeling' or 'Digests'.
58- The sub-sections ideally follow the same structure:
58+ Each sub-section should deal with one specific subject, for example 'Threat modeling',
59+ or a single project such as the OWASP 'Threat Dragon' Builder/Tool project.
5960
60- 1 . Overview, summarising the subject at an introductory level
61- 2 . Main body, explaining the subject to a medium/general level
62- 3 . Further reading, providing links to the subject at an advanced/detailed level
63- 4 . Resources, providing links to tools and applications that may be used when working within this domain
61+ Sub-sections that describe an individual project should follow the same structure:
62+
63+ 1 . Introduction, summarising the project at a very high level:
64+ _ supply a couple of sentences on the project including its status as an OWASP project and where to find it_
65+ 2 . The 'What', explaining what the project is to a general level:
66+ _ go into more detail about the project so that a developer can gain an overview of what this project can provide for them_
67+ 3 . The 'Why', explaining why developers will want to use the project:
68+ _ provide more context for project that allows developers to determine whether to use it in their team_
69+ 4 . The 'How', describe how to get started with the project
70+ _ give a brief outline of how the project provides value for a web application development team_
71+ _ Do not repeat the project documentation itself; ideally provide a primer and a pointer to the project documentation_
72+ 5 . Further reading or resources, if any, providing links on the project at an advanced/detailed level
73+
74+ Note that the page describing a project should not be the same as the project documentation on the OWASP site,
75+ the Developer Guide should strive to be a ' TL;DR ' for the project running to one or maybe two pages.
6476
6577### Pull requests
6678
0 commit comments