[GNUnet-SVN] [lsd0001] branch master updated: sketch what LSDs are about

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository lsd0001.

The following commit(s) were added to refs/heads/master by this push:
     new 7e2a72c  sketch what LSDs are about
7e2a72c is described below

commit 7e2a72ccdbb1f58f76b2059261802447c6b251a6
Author: Christian Grothoff <address@hidden>
AuthorDate: Wed Jul 11 18:47:15 2018 +0200

    sketch what LSDs are about
---
 lsd0001.texi | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 92 insertions(+), 7 deletions(-)

diff --git a/lsd0001.texi b/lsd0001.texi
index 16938a2..d043112 100644
--- a/lsd0001.texi
+++ b/lsd0001.texi
@@ -2,9 +2,9 @@
 @c -*-texinfo-*-
 
 @c %**start of header
address@hidden lsd0000.info
address@hidden lsd0001.info
 @documentencoding UTF-8
address@hidden GNUnet Reference Manual
address@hidden LSD 0001: The Living Specification Document Process
 @exampleindent 2
 @c It seems as if this breaks some old garbage version of
 @c texinfo running on some systems. FIXME!!!
@@ -44,9 +44,9 @@ Foundation Web site at 
@url{http://www.gnu.org/licenses/gpl.html}.
 @end direntry
 
 @titlepage
address@hidden LSD 0000
address@hidden LSD Template
address@hidden The GNUnet Developers
address@hidden LSD 0001
address@hidden The Living Specification Document Process
address@hidden Christian Grothoff (2018-)
 
 @page
 @vskip 0pt plus 1filll
@@ -61,11 +61,18 @@ Edition @value{EDITION} @*
 @node Top
 @top Introduction
 
-This living standards document describes ...
+Living Specification Documents (LSDs) document GNUnet protocols
+and processes.  This document describes the format, processes
+associated with writing LSDs, and provides a justification
+for this process.
 
 @menu
 
 * Abstract::                            Abstract
+* Motivation::                          Motivation
+* Format::                              Format
+* Maintenance::                         Maintenance
+* Birth::                               Birth
 * GNU Free Documentation License::
 
 @end menu
@@ -73,7 +80,85 @@ This living standards document describes ...
 @node Abstract
 @chapter Abstract
 
-This is a template.
+The goal of Living Specification Documents (LSDs) is to document the
+GNUnet system.  LSDs should evolve with the implementation while
+allowing implementations to reference a precise version of the
+document.  Each LSD must have an editor associated with it
+who maintains the document.  LSDs must be released under the
+GNU Free Documentation License and many not describe techniques
+encumbered by patents that would limit distribution under the
+GNU General Public License.
+
+
address@hidden Motivation
address@hidden Motivation
+
+The IETF has demonstrated how to not develop specifications.  The RFC
+process is intransparent (lots of private deals behind the scenes by
+ADs), slow (it can take many years to get an RFC approved) and
+political.  Technical excellence and following the procedures is no
+guarantee that an RFC will be published, resulting in many aspects of
+the Internet not being documented.  Despite the name, RFCs once
+published are fixed, and require major work even for minor
+clarifications.  The RFC editor function is centralized and the
+effective need to attend costly IETF meetings in person hinders
+broader participation.
+
+
address@hidden Format
address@hidden Format
+
+LSDs must be stored with an autotools-compatible build system in Git
+repositories.  The actual text must be written in GNU Texinfo format.
+The build system must support the generation of GNU info, HTML and PDF
+output formats.
+
+Each commit in the Git repositories must be signed by a GnuPG key.
+The current editor must be clearly indicated at the beginning
+of the document using the @@author tag.  Previous editors should
+be credited by year of maintainership.
+
+Repositories of important LSDs may include translations into
+other languages.  However, generally the primary language used
+in an LSD should be English.
+
address@hidden @node Referencing
address@hidden @section Referencing
address@hidden TBD
+
+
address@hidden Maintenance
address@hidden Maintenance
+
+The editor is ultimately responsible for the development of the LSD.
+This primarily includes ensuring at the text accurately and clearly
+describes the respective protocol or process.  The editor of an LSD
+must be reachable under @code{lsdXXXX@@gnunet.org}.
+
+Upon resignation, the editor should either suggest a replacement from
+the community or announce the death of the LSD, creating a Dead and
+Obsolete Document (DOD).  DODs may be archieved for archeologists, but
+should not be referenced from LSDs.
+
+
address@hidden Birth
address@hidden Birth
+
+LSDs are created by GNUnet a community member who sees an area where
+low-level technical documentation is required.  The community member
+should then try to precisely define the scope of the LSD and receive
+approval from a Git administrator.  The Git administrator will then
+setup the e-mail account forwarding and reserve an LSD number with the
+GNUnet Assigned Numbers Authority (@uref{LSD0002}).
+
+Git administrators should consider whether the subject is appropriate
+for an LSD.  Inappropriate subjects include end-user installation and
+usage instructions, and high-level developer documentation (i.e. how
+to use APIs).  Bit-level documentation of protocols or components
+used in protocols are appropriate for LSDs.
+
+
+
 
 
 @c *********************************************************************

-- 
To stop receiving notification emails like this one, please contact
address@hidden