[Owasp-leaders] Proposal for changing OWASP Documentation
jim.manico at owasp.org
Wed Feb 17 04:48:29 UTC 2016
There is plenty of good content on the wiki. I think "migration of
content" is probably more realistic that "starting over". Just a
thought, but please do as you wish as long as you do not delete the
wiki. It's in heavy active use.
On 2/16/16 9:41 PM, johanna curiel curiel wrote:
> >>I do not think - at all - that starting over is a good idea. There are thousands of
> hours of work in the wiki that should not be so quickly dismissed. And
> there are plenty of people still actively working on the wiki.
> Jim, Jim... you sound like a dev in love with his legacy ;-p.
> Sometimes, you need to kill your darlings. I like hearing solutions
> and unfortunately revising 8000+ content and hiring skilled force for
> that is not feasible imho.
> I respect and understand your pov but the documentation projects have
> their own set of necessities and appropriate experts/authors to carry
> on these task. Also, they have the materials and scope that need
> proper revision. If they start with these set of projects (OpenSamm,
> Code Review, Developer guide, Security Framework) and implement many
> of the things in the Testing guide ,it will provide cohesive content,
> something that we are missing from the wiki. With the support of
> Security Framework project leaders to manage the system, I think this
> consider a feasible solution.
> One that I think deserves the try.
> On Wed, Feb 17, 2016 at 12:30 AM, Jim Manico <jim.manico at owasp.org
> <mailto:jim.manico at owasp.org>> wrote:
> I do not think - at all - that starting over is a good idea. There
> are thousands of hours of work in the wiki that should not be so
> quickly dismissed. And there are plenty of people still actively
> working on the wiki.
> Keep in mind, starting over means folks need to build all this new
> content from scratch. It is not easy to find skilled folks to add
> all that new content, which takes us back to square one.
> One page at at a time. If you see any content that is out of date,
> please continue to inform me directly and I'll do something about
> it as quickly as I can with the help of the other editors who
> continue to work on the wiki.
> - Jim
> On 2/16/16 9:26 PM, johanna curiel curiel wrote:
>> >>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 categorizing.
>> 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 feasible.
>> 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 <mailto:jim.manico at owasp.org>> wrote:
>> 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
>> > *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
>> 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.
>>> 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
>>> 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?
>>> OWASP-Leaders mailing list
>>> OWASP-Leaders at lists.owasp.org
>>> <mailto:OWASP-Leaders at lists.owasp.org>
>> OWASP-Leaders mailing list
>> OWASP-Leaders at lists.owasp.org
>> <mailto:OWASP-Leaders at lists.owasp.org>
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OWASP-Leaders