Changes between Initial Version and Version 1 of DocFormat

Timestamp:

03/25/08 18:27:24 (16 years ago)

Author:

Aaron Falk

Comment:

--

DocFormat

@@ +1 @@
+[PageOutline]
+
+= Formatting for GENI Working Group Documents =
+
+== Formats. ==  
+GENI will require common formats for authoring, reviewing and publishing documents.
+
+=== Authoring tools/formats ===
+GENI working group documents be prepared using the Open Document text format (i.e., .odt).  There are many word processors available that will generate this format.  (See Appendix A, "Why ODF?" below, [http://en.wikipedia.org/wiki/OpenDocument_software here] for a catalog of tools and [http://en.wikipedia.org/wiki/OpenDocument_software_comparison here] for a comparison.)  !OpenOffice [http://download.openoffice.org/2.3.0/index.html?focus=download Writer] is one tool that works on PCs, Macs, and Unixes.  The GPO will make available a formatting template (.ott) containing the required front and back matter and standard styles.
+
+=== Reviewing tools/formats ===
+There are many ways to handle reviewer comments and the most appropriate one will vary depending on the size of the group doing the review and the number and size of changes to the document.  Specific review tools or processes will not be specified at this time.  As experience grows in reviewing GENI documents it may turn out that one technique is worth standardizing.  Some Open Document text format tools support change tracking and embedded notes (similar to MS Word), as do PDF tools such as Adobe Acrobat and Apple Preview.
+
+=== Publishing format: ===
+Documents will be published in PDF.
+
+== File Names. ==
+Working documents, i.e., documents not yet stable enough for addition to the archive, should be named in a way that gives some hints as to their nature.
+
+Documents should have the form {{{<wgname>-<subject>-<version_number>}}}.  For example, {{{fcfwg-rspec-00}}}.  Individual contributions should be named similarly and include the author's name.  For example, {{{smith-acmeproject-overview-00}}}.
+
+== Archiving ==
+
+=== Archiving for working drafts. ===
+Working drafts should be posted on the working groups wiki page in both ODT and PDF formats.  GDDs may be posted on a working group page only with the permission of the working group chair or system engineer.  Additionally, the GPO will provide a CVS/SVN access to working groups for document revision control if desired.
+
+The GPO will maintain a separate wiki for posting of GENI Unsolicited Documents (GUDs).
+
+=== Archiving for published documents. ===
+Once a document has become stable and is ready for other groups to use, it will be published on the geni.net web site. Separate web pages will be provided for working group and GPO documents.  It will be clear when documents have been revised or replaced by successors.
+
+== Workflow. ==
+Here is an example workflow to illustrate handling of GENI working group documents:
+
+ 1. Author would download the GPO document template
+ 1. The template is used as the basis for the document.  A draft is generated and saved as in .odt and .pdf formats and given a name and version number as described above.
+ 1. The author (with the permission of the wg chair) posts the document on the working group wiki page.
+ 1. Readers review the document and provide comments.
+ 1. Revisions are posted on the save wiki page with increased version numbers and a summary of changes in the document body.
+ 1. When the document is stable and ready for publishing, the PDF and ODT are sent to the GPO for addition to the documents page.
+
+
+----
+
+== Appendix A -- Why ODF? ==
+I see the requirements for document formats as the following:
+
+ * must support formats for working and archiving (not necessarily different)
+ * must support graphics
+ * must support tables
+ * working formats should support change tracking
+ * must support templates providing required boilerplate & common appearance
+ * archive format must be viewable on many platforms using free software
+ * must be easily archive-able
+ * must support an automated publication process
+
+In addition, the GPO does not wish to force anyone to buy a specific commercial product to participate in GENI design.
+
+The topic of authoring and publication formats is a perennial one in the IETF, where I've faced it many times as an author, working group chair, and publisher.  For its many great features Word has some shortcomings that make it undesirable.  Some of its shortcomings are detailed in this post to the IETF mail list: http://tinyurl.com/2n6rh6 .
+
+Now, you might say that working drafts authored by the WG SE might not run into the collaboration, version mismatch, or archiving limitations described in that posting.  I would disagree.  The primary goal of the working groups is to collaborate on these documents.
+
+The Open Document Format is an open, ISO standard for text, spreadsheets, and presentation.  Text formats (.odt) have native support in !OpenOffice, Mac !TextEdit (for Leopard), !GoogleDocs, MS Word (for Windows).  ODF includes formatting as well as content so authors have control of format (unlike !DocBook).  ODF is binary: a zipped archive of XML files and included graphics, it is self-contained and would require extra steps to use CVS text-mode.  The format and tools include support for dozens of languages, change tracking (not sure if this is better than MSW), tables, embedded graphics, formatting templates, native export to PDF.  
+
+As an open standard, it is gaining adoption worldwide by governments such as: Massachusetts, Belgium, France, Denmark, Norway, Malaysia, India, and Brazil.  WYSIWYG tools like !OpenOffice (which runs on Windows, Macs, Solaris, and FreeBSD) make for shorter learning curve by authors than !DocBook.  !OpenOffice, !GoogleDocs can import MS Word files and convert them to .odt files.