<div dir="ltr">Hi All<div><br></div><div>I have set Gary's ideas in a Wiki page for building a proposal</div><div><a href="https://www.owasp.org/index.php/Category:OWASP_Github_Documentation" target="_blank">https://www.owasp.org/index.php/Category:OWASP_Github_Documentation</a><br></div><div><br></div><div>Steps to follow for building a proposal to get traction (my advise here). We can discuss over mailing list to get things started but if you want to get the idea to reality, we need to make it a proposal.</div><div><br></div><div><ul><li>Add your name as volunteer if you support this initiative<br></li><li>Add you project if you want to transport documents  to this system</li><li>Draft plan section? Where to get started? Which projects?</li></ul><div>This is all suggestions to make this initiative a concrete one ;-)</div></div><div><br></div><div>Feel free to edit on the wiki and make suggestions</div><div><br></div><div>Cheers</div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Feb 15, 2016 at 6:26 AM, Seba <span dir="ltr"><<a href="mailto:seba@owasp.org" target="_blank">seba@owasp.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">hi Gary, all,<div><br></div><div>Great suggestion / thread.</div><div><br></div><div>With the SAMM project we have the same challenge (but a bit further down this line of thought).</div><div>The first release actually included an XML containing all the text for the SAMM projects (which also benefits translations, by the way).</div><div><br></div><div>With our new v1.1 release, we face the challenge to:</div><div>1) keep this in synch over the different v1.1 documents</div><div>2) "publish" this XML towards various outputs: wiki, tooling, indesign, ...</div><div>3) link to the various OWASP resources (currently covered with wiki categories - <a href="https://www.owasp.org/index.php/Category:SAMM-Resources" target="_blank">https://www.owasp.org/index.php/Category:SAMM-Resources</a></div><div><br></div><div>So: definitely interested to share the pain / improve our way of working :-)</div><div>How do we make this "actionable"?<br></div><div><br></div><div>regards</div><span class="HOEnZb"><font color="#888888"><div><br></div><div>Seba</div></font></span><div><br><br><div class="gmail_quote"><div><div class="h5"><div dir="ltr">On Sun, Feb 14, 2016 at 9:32 PM Gary Robinson <<a href="mailto:gary.robinson@owasp.org" target="_blank">gary.robinson@owasp.org</a>> wrote:<br></div></div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class="h5"><div dir="ltr"><p class="MsoNormal" style="font-size:12.8px">Hi Folks,</p><p class="MsoNormal" style="font-size:12.8px"> </p><p class="MsoNormal" style="font-size:12.8px">I want to reach out to the leaders and bring up the subject of OWASP docs projects, in fact all OWASP documentation including wiki and text available to our code projects as well.  I’ll try to keep this e-mail brief so won’t get bogged in details, but generally I want to know if the community experiences the same pains, see the same opportunities, or has other suggestions for improvement.</p><p class="MsoNormal" style="font-size:12.8px"> </p><p class="MsoNormal" style="font-size:12.8px">The issues that can arise from our current method of developing our various docs include:</p><p class="MsoNormal" style="font-size:12.8px"><br></p><p class="MsoNormal" style="font-size:12.8px"></p><ol style="font-size:12.8px"><li style="margin-left:15px">Draft content that exists in the wiki.  This may be in varying states (correct, incorrect, lousy, confused, etc.) and is visible to the internet and typically not clearly labelled as draft.  Google ‘owasp purple monkey dishwasher’ for an example of a draft wiki page visible to the internet.  This content also needs to get cleaned up after a project release.</li><li style="margin-left:15px">Substandard descriptions/content can get into our docs.  Getting people to review every line/example/diagram/appendix is difficult with a volunteer organization (as other threads have discussed)</li><li style="margin-left:15px">Duplications happen, as 10 different projects create/copy/paste their definitions of topics such as XSS, SQLi, CSRF, etc.  This wastes effort in an organization already constrained of active volunteers.</li><li style="margin-left:15px">Content gets out-of-date.  The work to create a new version of a doc project takes years.</li></ol><p style="font-size:12.8px"></p><p style="font-size:12.8px"></p><p class="MsoNormal" style="font-size:12.8px">I’m sure some readers will be mentally adding their own issues to this list.</p><p class="MsoNormal" style="font-size:12.8px"> </p><p class="MsoNormal" style="font-size:12.8px">Proposal:</p><p class="MsoNormal" style="font-size:12.8px"><br></p><p class="MsoNormal" style="font-size:12.8px">Bringing together discussions with a few people over the last few years (you know who you are), I’m proposing the following: we write our docs with reusable resources.  What would this mean?  Something similar to the following:</p><p class="MsoNormal" style="font-size:12.8px"><span style="font-family:Symbol"><span style="font-stretch:normal;font-size:7pt;font-family:'Times New Roman'"><br></span></span></p><p class="MsoNormal" style="font-size:12.8px"></p><ol style="font-size:12.8px"><li style="margin-left:15px">We dump all of the content from our wiki, current docs, descriptions in code tools, etc.  We put it into markup (as some projects are already doing) and add it to source code repositories.</li><li style="margin-left:15px">We share doc markup files <u>across ALL docs and code projects</u>.  For example, imagine we have a folder for SQLi.  This directory contains the OWASP ‘golden source’ for SQLi definition, examples, code, tests, etc.  Repeat for all other AppSec issues (CSRF, cert pinning, etc.).  We use a mechanism to ‘compile’ these markdown files into PDFs and integrate into code project HTML pages.</li><li style="margin-left:15px">Similar to good coding projects, we control who can edit the files under certain directories – people we know have expertise in an area.  Edits get peer reviewed before submission.  Other people can suggest edits and prove their experience to the existing team to join it.</li><li style="margin-left:15px">We allow anyone to ‘include’ this markup file into their project.  So if the Code Review Guide wants to add a section on SQLi, and needs a definition, I don’t write it (or copy from wiki), I simply include the relevant markup file.  Same for testing guide, dev guide, ZAP hints page, security shepherd info page, cheetsheet, and on and on.</li><li style="margin-left:15px">We allow all of our docs, plus the wiki, plus all code projects, to dynamically use an markup file update.  We make this ‘real time’.  This needs an example.  Say in March a massive change occurs in the world of SQLi.  Right now any project that talks about SQLi would need to manually go in and update, and those updates will be of varying quality and content.  If, instead, one (true) source file was update, all those other projects could spot the change and automatically rebuild themselves, meaning the next person to download a development guide PDF, or view the wiki, would get the updated SQLi information.</li><ol><li style="margin-left:15px">This is a big change.  This may be a controversial change.  <u>However it would greatly reduce our workload</u> (only one markup document needs to get updated).  It will also <u>greatly reduce review tasks</u>, as everyone is sharing core content which is reviewed once.  It also improves our image to the world, as all projects have the same great descriptions and content.</li><li style="margin-left:15px"><span style="font-family:'Courier New'"><span style="font-stretch:normal;font-size:7pt;font-family:'Times New Roman'">  </span></span>This change also improves our responsiveness.  Imagine a heartbleed type issue being reflected in all OWASP code and documentation projects, as well as the wiki/cheetsheets, within a few days?  (simply the time for the team to agree updates to the text/examples/descriptions, review, and submit)</li></ol><li style="margin-left:15px"><span style="font-family:Symbol"><span style="font-stretch:normal;font-size:7pt;font-family:'Times New Roman'"> </span></span>We should also make these markup files available to anyone on the internet (read only).  This way the source descriptions become an OWASP resource it itself, and anyone out there needing to spread the word on AppSec has easy access to rock solid, up-to-date definitions.<br></li></ol><p style="font-size:12.8px"></p><p style="font-size:12.8px"></p><p class="MsoNormal" style="font-size:12.8px">This changes the model, from people like myself who run ‘projects’, to smaller expert teams who know ‘technologies’ (such as SQLi or IIS secure configuration).  It focuses people where they want to be on docs projects, but easily shares that knowledge across all OWASP (and more) projects.  It also means there’d never be another need to clean-up the wiki – it would always be based off the markup content.</p><p class="MsoNormal" style="font-size:12.8px"><br></p><p class="MsoNormal" style="font-size:12.8px"><b>Big downside</b>: there’s a large piece of work to start it off.  All content would need to get organized, put into sensible structure, converted to markdown, argued over, ‘experts’ defined and assigned, etc.  I doubt this would be a volunteer effort, and may need contractor involvement.  Could this be combined with the OWASP wiki redesign?</p><p class="MsoNormal" style="font-size:12.8px"><br></p><p class="MsoNormal" style="font-size:12.8px">So… the ask from the community, what are your thoughts? Could this be a viable option to save us time on docs/descriptions and increase quality?  Would there be funds to perform the initial conversion of everything into markup pages?  Would there be resistance to working in this new model?</p><p class="MsoNormal" style="font-size:12.8px"><br></p><p class="MsoNormal" style="font-size:12.8px">Gary</p><div style="font-size:12.8px"></div></div></div></div>
_______________________________________________<span class=""><br>
OWASP-Leaders mailing list<br>
<a href="mailto:OWASP-Leaders@lists.owasp.org" target="_blank">OWASP-Leaders@lists.owasp.org</a><br>
<a href="https://lists.owasp.org/mailman/listinfo/owasp-leaders" rel="noreferrer" target="_blank">https://lists.owasp.org/mailman/listinfo/owasp-leaders</a><br>
</span></blockquote></div></div></div>
<br>_______________________________________________<br>
OWASP-Leaders mailing list<br>
<a href="mailto:OWASP-Leaders@lists.owasp.org">OWASP-Leaders@lists.owasp.org</a><br>
<a href="https://lists.owasp.org/mailman/listinfo/owasp-leaders" rel="noreferrer" target="_blank">https://lists.owasp.org/mailman/listinfo/owasp-leaders</a><br>
<br></blockquote></div><br></div>