[Bug 1156709] Re: Preseed commands and parameters should be enumerated and explained

[Lucas Yamanishi]

** Description changed:

  The Preseed documentation strategy seems to be primarily examples with
- comments and explanations, but I've found it is very incomplete.  It is
- very frustrating to read through the documentation and not find simple
- answer to questions like:  What does the number between the minimum and
- maximum size for a partition mean?  Or, is partition size specified in
- cylinders, blocks, segments, extents, bytes, kilobytes, kibibytes,
- megabytes or mebibytes?
+ comments and explanations, but it is not complete.  From a user's
+ perspective, it is very frustrating to read through the documentation
+ and not find simple answer to questions like:  What does the number
+ between the minimum and maximum size for a partition mean?  Or, is
+ partition size specified in cylinders, blocks, segments, extents, bytes,
+ kilobytes, kibibytes, megabytes or mebibytes?  These are documented, but
+ it requires digging through the source repositories to find them--
+ http://anonscm.debian.org/gitweb/?p=d-i/debian-
+ installer.git;a=tree;f=doc/devel
  
- My suggestion: enumerate and explain each command, sub-command, and
+ My suggestion: Enumerate and explain each command, sub-command, and
  parameter.  Say what is optional and what is require.  List valid input
  for each parameter, including data type, unit, or valid string values.
  And if there is a default, say what it is.
  
- Examples:
+ Full Backus-Naur Form documentation like is available in the developer
+ docs isn't necessary, but links to Primary Sources would be very
+ helpful.
+ 
+ Examples of good web-based documentation:
  http://docs.fedoraproject.org/en-US/Fedora/18/html/Installation_Guide/s1-kickstart2-options.html
  http://users.suse.com/~ug/autoyast_doc/configuration.html
  http://docs.oracle.com/cd/E19253-01/817-5506/6mkv6ki73/index.html
  http://www.hp.com/go/ignite-ux-docs
  http://www.openbsd.org/cgi-bin/man.cgi?query=bgpd.conf

-- 
You received this bug notification because you are a member of Ubuntu
Foundations Bugs, which is subscribed to installation-guide in Ubuntu.
https://bugs.launchpad.net/bugs/1156709

Title:
  Preseed commands and parameters should be enumerated and explained

Status in “installation-guide” package in Ubuntu:
  New

Bug description:
  The Preseed documentation strategy seems to be primarily examples with
  comments and explanations, but it is not complete.  From a user's
  perspective, it is very frustrating to read through the documentation
  and not find simple answer to questions like:  What does the number
  between the minimum and maximum size for a partition mean?  Or, is
  partition size specified in cylinders, blocks, segments, extents,
  bytes, kilobytes, kibibytes, megabytes or mebibytes?  These are
  documented, but it requires digging through the source repositories to
  find them-- http://anonscm.debian.org/gitweb/?p=d-i/debian-
  installer.git;a=tree;f=doc/devel

  My suggestion: Enumerate and explain each command, sub-command, and
  parameter.  Say what is optional and what is require.  List valid
  input for each parameter, including data type, unit, or valid string
  values.  And if there is a default, say what it is.

  Full Backus-Naur Form documentation like is available in the developer
  docs isn't necessary, but links to Primary Sources would be very
  helpful.

  Examples of good web-based documentation:
  http://docs.fedoraproject.org/en-US/Fedora/18/html/Installation_Guide/s1-kickstart2-options.html
  http://users.suse.com/~ug/autoyast_doc/configuration.html
  http://docs.oracle.com/cd/E19253-01/817-5506/6mkv6ki73/index.html
  http://www.hp.com/go/ignite-ux-docs
  http://www.openbsd.org/cgi-bin/man.cgi?query=bgpd.conf

To manage notifications about this bug go to:
https://bugs.launchpad.net/ubuntu/+source/installation-guide/+bug/1156709/+subscriptions