[Owasp-leaders] Proposal for changing OWASP Documentation

Gary Robinson gary.robinson at owasp.org
Wed Feb 17 19:48:02 UTC 2016


Hi All,

I think we are all on the same page here.  As Johanna says no one is
deleting the wiki, or demanding everything stops and moved to markdown.

Instead let's all have a discussion about what would work, what everyone
would want to use, bow we could collaborate and save effort, and trial it
for a few projects.  As things grow and are established to work then we
look to expand it. (Or don't expand it if it doesn't work)

I don't know that end consumers of content would only have access to the
markdown.  Instead it'd be great to have automatic processes/tools that
allow them to access it via various views like wiki pages, PDF books, HTML
pages in ZAP help page, and any other format that helps the cause. This can
all come from the same source text.

I think this discussion reflects an interest into looking at this way of
working.  As this discussion has gone on, the notion of trailing via some
projects seems more attractive than trying to dump the wiki in one lump,
that makes sense.  It think the discussion has evolved well and we'll
attempt to make it into a workable proposal.

Gary
On 17 Feb 2016 5:38 a.m., "johanna curiel curiel" <johanna.curiel at owasp.org>
wrote:

> Comparing markdown to XML is quite big
> No one wants to kill the wiki nor replace its content
>
> Btw wiki markdown  is not that huge difference with github. Is just a way
> to tryout another forms of collaborations not supported by the wiki
>
> Please , read the proposal plan over.
>
> On Wednesday, February 17, 2016, Andrew van der Stock <vanderaj at owasp.org>
> wrote:
>
>> Replacing many years of work does not advance the work, nor consider all
>> the use cases.
>>
>> What I would suggest is for current and active project leaders to deliver
>> in the new way, rather than say all stuff has to be transformed before it
>> can be useful in a second life. Personally, as much as I like the idea of
>> having our stuff retrievable by machines, a great deal of our stuff is
>> designed to be consumed by humans, and our work flows are human in nature.
>>
>> We need to be aware of this. OWASP has had several projects die because
>> they decided to go into technology deep dive mode, without a clear
>> objective and mechanism for contributors and consumers to
>>
>>
>>    - plan
>>    - contribute
>>    - maintain
>>    - discover
>>    - consume
>>    - use
>>
>> our diverse materials.
>>
>> Just saying "throw it out and start again", that's not good enough. I was
>> there when XML killed the OWASP Developer Guide in 2003. It wasn't the only
>> reason, but it was a big reason.
>>
>> We can't ask humans to consume XML or markdown. We need our efforts to be
>> aligned to our use cases, and not tied up in activities that do not produce
>> value. I am all for the killing or incorporating of old content and
>> aligning it with our strategic goals:
>>
>>
>>
>>    - Education
>>    - Outreach and awareness
>>    - Improving the Projects platform
>>    - Getting the chapters involved in projects
>>    - Improving our infrastructure to support our strategic goals.
>>
>>
>> I am not in favor of ALL THE THINGS MARKDOWN NOW! Let's try to work out
>> how we support our mission, ensure our key workflows, contributors and
>> consumers are included in any effort to make things better, once we've
>> decided on "what's better".
>>
>> thanks
>> Andrew
>>
>> On Wed, Feb 17, 2016 at 3:59 PM, johanna curiel curiel <
>> johanna.curiel at owasp.org> wrote:
>>
>>> Hey Jim, no one has implied to delete the wiki .
>>>
>>> Just to provide these documentation projects an opportunity to start
>>> moving their content and make it more cohesive and sharing.
>>>
>>> The wiki is the actual OWASP portal so before there is a full
>>> replacement it will take some years.
>>>
>>> But as people work on more cohesive , collaborative way and managing
>>> content wise with Github markdown as proposed by Gary, I believe that you
>>> can take out a lot of redundant content and automatically, this will become
>>> 'obsolete'. A lot of the possibilities of exporting content and
>>> collaboration are much better with Github markdown (such as transforming
>>> content automatically to other formats or reusing it). We start over on the
>>> Github.
>>>
>>> We are planning to do the same with the Project's portal as the content
>>> has become unmanageable and not so user friendly. It does not support many
>>> of our necessary processes.
>>>
>>>  Like the legacy app, you can't just get rid off it from one day to
>>> another but it requires a transformation and migration ;-).
>>>
>>> Hope this clarifies the purpose and goal.
>>>
>>> Cheers
>>>
>>> Johanna
>>>
>>>
>>>
>>> On Wed, Feb 17, 2016 at 12:48 AM, Jim Manico <jim.manico at owasp.org>
>>> wrote:
>>>
>>>> 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>
>>>> 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>
>>>>> 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>
>>>>>> 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
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>
>>> _______________________________________________
>>> OWASP-Leaders mailing list
>>> OWASP-Leaders at lists.owasp.org
>>> https://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/03af24ac/attachment-0001.html>


More information about the OWASP-Leaders mailing list