[Owasp-leaders] Proposal for changing OWASP Documentation

johanna curiel curiel johanna.curiel at owasp.org
Wed Feb 17 04:26:46 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 categorise pages that need

I believe in divide and conquer but also , at a certain moment, you need to
focus on the approach.

I don't think walking through those 8000+ is realistic, cheap or feasible
not even for a hired qualified team.

I  think this problem is similar to having a very old, big, legacy
application no one understands and no one wants to work with. What most
business do?

*Start from scratch, a new one.*

I think the focus here is for documentation existing projects to markup
their documents and work form there. Focusing on those 8000+ is not

As Jim said, the people that wants to edit seem  not to be *qualified*
enough to edit and the people that are *qualified*, well, they do not have
time nor feel like editing on the wiki ;-P

On Tue, Feb 16, 2016 at 11:53 PM, Jim Manico <jim.manico at owasp.org> wrote:

> Gary,
> 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. :)
> Aloha,
> Jim
> 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 listOWASP-Leaders at lists.owasp.orghttps://lists.owasp.org/mailman/listinfo/owasp-leaders
> _______________________________________________
> 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/20160217/e2a94d5e/attachment.html>

More information about the OWASP-Leaders mailing list