[Owasp-leaders] Proposal for changing OWASP Documentation

Jim Manico jim.manico at owasp.org
Wed Feb 17 03:53:05 UTC 2016


Good stuff. I think the best way to approach this is to get a team to 
walk through our 8000+ page wiki and categorize pages that need 
categorizing. That would "bucket" content as you suggested in prep for 
any move into "folders" (and make the wiki a better place as it is). We 
already have a wiki template system to help mark old or dead content ( 
https://www.owasp.org/index.php/Template:TaggedDocument ) and wiki 
markup makes content categorization easy by adding a wiki category to 
any page.

I am personally a big fan of the wiki and wiki-markup. I would hate to 
dump the many thousand people-years of work in there.

 > *Big downside*: 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?

Yea, exactly. The process of trying to update the wiki (or at least 
handle dated content that others are concerned about) is already in 
place and some folks like myself and members the wiki editorial team 
have slowly been going over wiki content and trying to make it more 
honest on a page by page level. The problem is the sheer volume and the 
lack of tools to aid in the process.

Another problem is how do we hire? We need content folks who understand 
application security, these are not cheap hires. We've made the call for 
volunteers to help with wiki cleanup, but only found a few volunteers to 
help and only 2 are active.  Any honestly, we need rather thoughtful and 
skilled volunteers who really get application security, and they are 
hard to find in 2016.

I'm not sure what the best path is to handle the wiki mess before us, so 
in the meantime I'm crunching through one page at a time, one request at 
a time, and one cleanup at a time. If anyone wants to help accelerate 
this with hands-on help and assistance, I'm all ears and am eager for 
your help. In my experience a lot of folks have ideas and plans to make 
the wiki better, but very few are willing to do the work. I mean that 
respectfully, I understand how busy everyone is.

I think the best kind of leadership is getting your hands dirty and 
leading by example. If you want to help dive in and start looking at the 
scope of the wiki problem with me, sign up at 
https://lists.owasp.org/mailman/listinfo/owasp-wiki-editors and 
introduce yourself and expand on your plan. I'd be glad to give you a 
tour around the wiki and show you whats up. I do not blame you if you 
bail. Several folks joined with enthusiastic desire to help, but then 
bailed once they saw the scope of the problem. In the meantime, one page 
at a time is all I got. :)


On 2/14/16 1:30 PM, Gary Robinson wrote:
> Hi Folks,
> 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.
> The issues that can arise from our current method of developing our 
> various docs include:
>  1. 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.
>  2. 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)
>  3. 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.
>  4. Content gets out-of-date.  The work to create a new version of a
>     doc project takes years.
> I’m sure some readers will be mentally adding their own issues to this 
> list.
> Proposal:
> 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:
>  1. 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.
>  2. We share doc markup files _across ALL docs and code projects_. 
>     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.
>  3. 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.
>  4. 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.
>  5. 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.
>      1. This is a big change.  This may be a controversial change.
>         _However it would greatly reduce our workload_ (only one
>         markup document needs to get updated).  It will also _greatly
>         reduce review tasks_, 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.
>      2. 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)
>  6. 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.
> 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.
> *Big downside*: 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?
> 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?
> Gary
> _______________________________________________
> OWASP-Leaders mailing list
> OWASP-Leaders at lists.owasp.org
> https://lists.owasp.org/mailman/listinfo/owasp-leaders

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.owasp.org/pipermail/owasp-leaders/attachments/20160216/26655f3c/attachment-0001.html>

More information about the OWASP-Leaders mailing list