[Owasp-leaders] Proposal for changing OWASP Documentation

Jim Manico jim.manico at owasp.org
Wed Feb 17 04:48:29 UTC 2016


Johanna,

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.

Aloha,
- Jim

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:
>>
>>         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 list
>>>         OWASP-Leaders at lists.owasp.org
>>>         <mailto:OWASP-Leaders at lists.owasp.org>
>>>         https://lists.owasp.org/mailman/listinfo/owasp-leaders
>>
>>
>>         _______________________________________________
>>         OWASP-Leaders mailing list
>>         OWASP-Leaders at lists.owasp.org
>>         <mailto: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/7b64a87a/attachment-0001.html>


More information about the OWASP-Leaders mailing list