diff --git a/.golangci.yml b/.golangci.yml
index ea972134..3877aa3d 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -1,3 +1,6 @@
+issues:
+  exclude-files:
+    - "example_test\\.go$"
 linters-settings:
   errcheck:
     check-type-assertions: true
diff --git a/diskfs.go b/diskfs.go
index f0952a09..75fa5367 100644
--- a/diskfs.go
+++ b/diskfs.go
@@ -8,98 +8,6 @@
 // This is not intended as a replacement for operating system filesystem and disk drivers. Instead,
 // it is intended to make it easy to work with partitions, partition tables and filesystems directly
 // without requiring operating system mounts.
-//
-// Some examples:
-//
-// 1. Create a disk image of size 10MB with a FAT32 filesystem spanning the entire disk.
-//
-//		import diskfs "github.com/diskfs/go-diskfs"
-//		size := 10*1024*1024 // 10 MB
-//
-//		diskImg := "/tmp/disk.img"
-//		disk := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
-//
-//		fs, err := disk.CreateFilesystem(0, diskfs.TypeFat32)
-//
-//	 2. Create a disk of size 20MB with an MBR partition table, a single partition beginning at block 2048 (1MB),
-//	    of size 10MB filled with a FAT32 filesystem.
-//
-//	    import diskfs "github.com/diskfs/go-diskfs"
-//
-//	    diskSize := 10*1024*1024 // 10 MB
-//
-//	    diskImg := "/tmp/disk.img"
-//	    disk := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
-//
-//	    table := &mbr.Table{
-//	    LogicalSectorSize:  512,
-//	    PhysicalSectorSize: 512,
-//	    Partitions: []*mbr.Partition{
-//	    {
-//	    Bootable:      false,
-//	    Type:          Linux,
-//	    Start:         2048,
-//	    Size:          20480,
-//	    },
-//	    },
-//	    }
-//
-//	    fs, err := disk.CreateFilesystem(1, diskfs.TypeFat32)
-//
-//	 3. Create a disk of size 20MB with a GPT partition table, a single partition beginning at block 2048 (1MB),
-//	    of size 10MB, and fill with the contents from the 10MB file "/root/contents.dat"
-//
-//	    import diskfs "github.com/diskfs/go-diskfs"
-//
-//	    diskSize := 10*1024*1024 // 10 MB
-//
-//	    diskImg := "/tmp/disk.img"
-//	    disk := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
-//
-//	    table := &gpt.Table{
-//	    LogicalSectorSize:  512,
-//	    PhysicalSectorSize: 512,
-//	    Partitions: []*gpt.Partition{
-//	    {
-//	    LogicalSectorSize:  512,
-//	    PhysicalSectorSize: 512,
-//	    ProtectiveMBR:      true,
-//	    },
-//	    },
-//	    }
-//
-//	    f, err := os.Open("/root/contents.dat")
-//	    written, err := disk.WritePartitionContents(1, f)
-//
-//	 4. Create a disk of size 20MB with an MBR partition table, a single partition beginning at block 2048 (1MB),
-//	    of size 10MB filled with a FAT32 filesystem, and create some directories and files in that filesystem.
-//
-//	    import diskfs "github.com/diskfs/go-diskfs"
-//
-//	    diskSize := 10*1024*1024 // 10 MB
-//
-//	    diskImg := "/tmp/disk.img"
-//	    disk := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
-//
-//	    table := &mbr.Table{
-//	    LogicalSectorSize:  512,
-//	    PhysicalSectorSize: 512,
-//	    Partitions: []*mbr.Partition{
-//	    {
-//	    Bootable:      false,
-//	    Type:          Linux,
-//	    Start:         2048,
-//	    Size:          20480,
-//	    },
-//	    },
-//	    }
-//
-//	    fs, err := disk.CreateFilesystem(1, diskfs.TypeFat32)
-//	    err := fs.Mkdir("/FOO/BAR")
-//	    rw, err := fs.OpenFile("/FOO/BAR/AFILE.EXE", os.O_CREATE|os.O_RDRWR)
-//	    b := make([]byte, 1024, 1024)
-//	    rand.Read(b)
-//	    err := rw.Write(b)
 package diskfs
 
 import (
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 00000000..cfb9ca62
--- /dev/null
+++ b/example_test.go
@@ -0,0 +1,122 @@
+package diskfs_test
+
+import (
+	"crypto/rand"
+	"os"
+
+	diskfs "github.com/diskfs/go-diskfs"
+	"github.com/diskfs/go-diskfs/disk"
+	"github.com/diskfs/go-diskfs/filesystem"
+	"github.com/diskfs/go-diskfs/partition/gpt"
+	"github.com/diskfs/go-diskfs/partition/mbr"
+)
+
+// Create a disk image of size 10MB with a FAT32 filesystem spanning the entire disk.
+func ExampleCreate_fat32() {
+
+	var size int64
+	size = 10 * 1024 * 1024 // 10 MB
+
+	diskImg := "/tmp/disk.img"
+	defer os.Remove(diskImg)
+	theDisk, _ := diskfs.Create(diskImg, size, diskfs.SectorSizeDefault)
+
+	fs, err := theDisk.CreateFilesystem(disk.FilesystemSpec{
+		Partition: 0,
+		FSType:    filesystem.TypeFat32,
+	})
+}
+
+// Create a disk of size 20MB with an MBR partition table, a single partition beginning at block 2048 (1MB),
+// of size 10MB filled with a FAT32 filesystem.
+func ExampleCreate_mbr() {
+	var size int64
+	size = 20 * 1024 * 1024 // 20 MB
+
+	diskImg := "/tmp/disk.img"
+	theDisk, _ := diskfs.Create(diskImg, size, diskfs.SectorSizeDefault)
+
+	table := &mbr.Table{
+		LogicalSectorSize:  512,
+		PhysicalSectorSize: 512,
+		Partitions: []*mbr.Partition{
+			{
+				Bootable: false,
+				Type:     mbr.Linux,
+				Start:    2048,
+				Size:     20480,
+			},
+		},
+	}
+
+	theDisk.Partition(table)
+
+	fs, err := theDisk.CreateFilesystem(disk.FilesystemSpec{
+		Partition: 1,
+		FSType:    filesystem.TypeFat32,
+	})
+}
+
+// Create a disk of size 20MB with a GPT partition table, a single partition beginning at block 2048 (1MB), of size 10MB, and fill with the contents from the 10MB file "/root/contents.dat"
+func ExampleCreate_gpt() {
+	var size int64
+	size = 20 * 1024 * 1024 // 20 MB
+
+	diskImg := "/tmp/disk.img"
+	defer os.Remove(diskImg)
+	theDisk, _ := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
+
+	table := &gpt.Table{
+		LogicalSectorSize:  512,
+		PhysicalSectorSize: 512,
+		ProtectiveMBR:      true,
+		Partitions: []*gpt.Partition{
+			{
+				//FIXME: what should I put here? Start and Size were missing in the original example
+			},
+		},
+	}
+
+	theDisk.Partition(table)
+
+	f, err := os.Open("/root/contents.dat")
+	written, err := theDisk.WritePartitionContents(1, f)
+}
+
+// Create a disk of size 20MB with an MBR partition table, a single partition beginning at block 2048 (1MB),
+// of size 10MB filled with a FAT32 filesystem, and create some directories and files in that filesystem.
+func ExampleCreate_fat32WithDirsAndFiles() {
+	var size int64
+	size = 20 * 1024 * 1024 // 20 MB
+
+	diskImg := "/tmp/disk.img"
+	defer os.Remove(diskImg)
+	theDisk, _ := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
+
+	table := &mbr.Table{
+		LogicalSectorSize:  512,
+		PhysicalSectorSize: 512,
+		Partitions: []*mbr.Partition{
+			{
+				Bootable: false,
+				Type:     mbr.Linux,
+				Start:    2048,
+				Size:     20480,
+			},
+		},
+	}
+
+	theDisk.Partition(table)
+
+	fs, err := theDisk.CreateFilesystem(disk.FilesystemSpec{
+		Partition: 1,
+		FSType:    filesystem.TypeFat32,
+	})
+
+	err = fs.Mkdir("/FOO/BAR")
+
+	rw, err := fs.OpenFile("/FOO/BAR/AFILE.EXE", os.O_CREATE|os.O_RDWR)
+	b := make([]byte, 1024, 1024)
+	rand.Read(b)
+	written, err := rw.Write(b)
+}