OWASP Press - Revision history

Dennis Groves: /* The OWASP Press Project */

2013-11-27T20:54:34Z

‎The OWASP Press Project

Dennis Groves: /* Licensing */

2013-11-27T20:49:54Z

‎Licensing

Dennis Groves: /* Licensing */

2013-11-27T20:49:30Z

‎Licensing

Dennis Groves: /* Licensing */

2013-11-27T20:43:04Z

‎Licensing

Dennis Groves at 20:41, 27 November 2013

2013-11-27T20:41:16Z

Dennis Groves: /* Project Leader */

2013-11-27T20:15:37Z

‎Project Leader

Dennis Groves at 20:14, 27 November 2013

2013-11-27T20:14:32Z

Dennis Groves at 19:27, 27 November 2013

2013-11-27T19:27:14Z

Dennis Groves: /* HOWTO Author and Publish using the OWASP Press */

2013-11-27T19:26:27Z

‎HOWTO Author and Publish using the OWASP Press

Dennis Groves: Instructions

2013-11-27T19:25:12Z

Instructions

@@ Line 9: / Line 9: @@
 ==The OWASP Press Project==
-The OWASP press project is proposal that allows community authoring with just in time publishing.
+The OWASP press project is proposal that allows community authoring and edditing with just in time publishing.
 Community authoring is fraught with challenges. Word documents with revisions on eventually crash, and so people eventually take to naming conventions to manage the versions. Additionally, there is only one canonical master; this makes authoring and editing in parallel impossible; and merging the resulting versions is an enormous time sink in and of itself. This only gets worse the larger the book is and the more authors that are involved.

@@ Line 35: / Line 35: @@
 The OWASP Press is licensed under the http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 license], so you can copy, distribute and transmit the work, and you can adapt it, and use it commercially, but all provided that you attribute the work and if you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.
-[https://github.com/ GitHub] is a free to use service, GitHub, Inc. owns the copyright on the github service.
+* [https://github.com/ GitHub] is a free to use service, GitHub, Inc. owns the copyright on the github service.
-[https://leanpub.com/ Leanpub] is a free to use service,  Ruboss Technology Corporation owns the copyright on the leanpub service.
+* [https://leanpub.com/ Leanpub] is a free to use service,  Ruboss Technology Corporation owns the copyright on the leanpub service.
 <!-- DO NOT ALTER OR REMOVE THE TEXT ON NEXT LINE -->

@@ Line 33: / Line 33: @@
 '''The OWASP Press is free to use. In fact it is encouraged!!!
-The OWASP Press is licensed under the http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 license], so you can copy, distribute and transmit the work, and you can adapt it, and use it commercially, but all provided that you attribute the work and if you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.
+[https://github.com/ GitHub] is a free to use service, GitHub, Inc. owns the copyright on the github service.
 <!-- DO NOT ALTER OR REMOVE THE TEXT ON NEXT LINE -->

@@ Line 31: / Line 31: @@
 ==Licensing==
-<!-- Instructions are in RED and should be removed from your document by deleting the text with the span tags.-->
+'''The OWASP Press is free to use. In fact it is encouraged!!!
-The OWASP Security Principles are licensed under the http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 license], so you can copy, distribute and transmit the work, and you can adapt it, and use it commercially, but all provided that you attribute the work and if you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.
+The OWASP Press is licensed under the http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 license], so you can copy, distribute and transmit the work, and you can adapt it, and use it commercially, but all provided that you attribute the work and if you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.
 <!-- DO NOT ALTER OR REMOVE THE TEXT ON NEXT LINE -->

@@ Line 126: / Line 126: @@
 |}
-= Authoring, Editing and Publishing =
+= Getting Started =
 == Leanpub ==

@@ Line 66: / Line 66: @@
 == Project Leader ==
 * [https://www.owasp.org/index.php/User:Dennis_Groves Dennis Groves]
 == Related Projects ==

← Older revision		Revision as of 20:14, 27 November 2013
Line 192:		Line 192:
	While I appreciate that this is somewhat manual, github has service hook's that could be used to automate this workflow completely. I am currently exploring the best way to do this. If the dropbox is hosted remotely as well then the [http://net.tutsplus.com/tutorials/other/the-perfect-workflow-with-git-github-and-ssh/ 'git -pull'] can be automated. This need to be followed by a publish request with leanpub; and while it has some authorisation tokens and oner 'anti-automation' cookies; it would be trivial for most of the OWASP community to issue the post request to leanpub in an automated way.		While I appreciate that this is somewhat manual, github has service hook's that could be used to automate this workflow completely. I am currently exploring the best way to do this. If the dropbox is hosted remotely as well then the [http://net.tutsplus.com/tutorials/other/the-perfect-workflow-with-git-github-and-ssh/ 'git -pull'] can be automated. This need to be followed by a publish request with leanpub; and while it has some authorisation tokens and oner 'anti-automation' cookies; it would be trivial for most of the OWASP community to issue the post request to leanpub in an automated way.

		+	=Editing=
		+	[http://criticmarkup.com CriticMarkup] is a way for authors and editors to track changes to documents in plain text. As with [http://en.wikipedia.org/wiki/Markdown Markdown], small groups of distinctive characters allow you to highlight insertions, deletions, substitutions and comments, all without the overhead of heavy, proprietary office suites.
		+
		+	'''The Three Laws'''
		+
		+	# Critic Markup shall be human readable. A human with a simple text editor can easily read and comprehend any text containing Critic Markup.
		+	# Critic Markup shall be computer readable except where it conflicts with rule 1. Markup syntax should be easily parsed with simple regular expressions to support a wide variety of implementations.
		+	# Critic Markup shall be compatible with existing markup syntax for Markdown, MultiMarkdown and HTML except where it conflicts with rules one or two. Many users of plain text write in combinations of Markdown and HTML. Critic Markup should work alongside that syntax.
		+
		+	'''The Basic Syntax'''
		+
		+	There are five types of Critic marks:
		+
		+	<pre>Addition {++ ++}
		+	Deletion {-- --}
		+	Substitution {~~ ~> ~~}
		+	Comment {>> <<}
		+	Highlight {{ }}{>> <<} </pre>
		+	Using these {~~ six ~> five ~~} basic marks you can {++ successfully ++} copy edit in plain text. {>> Although modern word processing programs can do some amazing things—adding charts, tables, and images, applying sophisticated formatting—there’s one thing they can’t do: Guarantee that the words I write today will be readable ten years from now. That’s just one of the reasons I prefer to work in plain text: It’s timeless. My grandchildren will be able to read a text file I create today, long after anybody can remember what the heck a .dotx file is. <<}
		+
		+	'''Conclusion'''
		+
		+	Combine this with [http://git-scm.com git version control] and you have a complete history of changes to your documents in plain text, including reviewer feedback! Now even reviewer can participate in the [http://scriptogr.am/dennis-groves/post/owasp-press OWASP Press].
	= Acknowledgements =		= Acknowledgements =

← Older revision		Revision as of 19:27, 27 November 2013
Line 241:		Line 241:
	__NOTOC__ <headertabs />		__NOTOC__ <headertabs />

−	[[Category:OWASP Project]] ~~[[Category:OWASP_Builders]] [[Category:OWASP_Defenders]]~~ [[Category:OWASP_Document]]	+	[[Category:OWASP Project]] [[Category:OWASP_Document]]

@@ Line 132: / Line 132: @@
 |}
-=FAQs=
+= HOWTO Author and Publish using the OWASP Press=
-<!-- Instructions are in RED and should be removed from your document by deleting the text with the span tags.-->
+[https://leanpub.com/ Leanpub] is a lean workflow applied to documentation. Publishing is indeed lean; as in [http://en.wikipedia.org/wiki/Lean_manufacturing Toyota lean]; in fact it is just-in-time like the [http://en.wikipedia.org/wiki/Qin_Dynasty Qin Dynasty's] [http://www.washingtonpost.com/national/health-science/chinese-terra-cotta-warriors-had-real-and-very-carefully-made-weapons/2012/11/26/999b9cb4-2840-11e2-b4e0-346287b7e56c_print.html terra cotta warriors]! In fact they have written a very interesting [https://leanpub.com/manifesto manifesto] about the future of publishing that I found to be very insightful and well researched. I highly recommend reading it if you are interested in such things.
-==How can I participate in your project?==
+After joining the site, you create a book by clicking a 'Create a lean pub book now' link; which takes you to a page that asks for the book title and a URL; and you submit the form with a 'create my book' button. Leanpub then publishes a manuscript folder to dropbox and shares it with you, and sets up a storefront for the book at the url you specified.
-==If I am not a programmer can I participate in your project?==
+The manuscript is written in markdown<ref>Markdown is a very cool plain-text format that can be compiled by tools like [http://johnmacfarlane.net/pandoc/ pandoc] into numerous outputs; including latex, mediawiki, doc, and html to name but a very few. Using pandoc the very same markdown text can easily be turned into mediawiki content for the OWASP wiki.
-Yes, you can certainly participate in the project if you are not a programmer or technical. The project needs different skills and expertise and different times during its development. Currently, we are looking for researchers, writers, graphic designers, and a project administrator.
+</ref>, However, since markdown is a simple markup format it doesn't have any file inclusion features, so everything is expected to be in a single file. This is a problem because it is very difficult for many authors to make changes to a single file, and also because it is simply nicer to separate out ideas that belong together into chapters.
 = Acknowledgements =