better documentation

README.md

@@ -108,6 +108,21 @@ You can later deserialize the result as follows:
 The `ReadFrom` function attempts to read the data into the existing
 BitSet instance, to minimize memory allocations.
 
+
+*Performance tip*: 
+When reading and writing to a file or a network connection, you may get better performance by 
+wrapping your streams with `bufio` instances.
+
+E.g., 
+```Go
+	f, err := os.Create("myfile")
+	w := bufio.NewWriter(f)
+```
+```Go
+	f, err := os.Open("myfile")
+	r := bufio.NewReader(f)
+```
+
 ## Memory Usage
 
 The memory usage of a bitset using `N` bits is at least `N/8` bytes. The number of bits in a bitset is at least as large as one plus the greatest bit index you have accessed. Thus it is possible to run out of memory while using a bitset. If you have lots of bits, you might prefer compressed bitsets, like the [Roaring bitmaps](http://roaringbitmap.org) and its [Go implementation](https://github.com/RoaringBitmap/roaring).

bitset.go

@@ -912,6 +912,13 @@ func (b *BitSet) BinaryStorageSize() int {
 // 1. uint64 length
 // 2. []uint64 set
 // Upon success, the number of bytes written is returned.
+//
+// Performance: if this function is used to write to a disk or network
+// connection, it might be beneficial to wrap the stream in a bufio.Writer.
+// E.g.,
+//
+//	      f, err := os.Create("myfile")
+//		       w := bufio.NewWriter(f)
 func (b *BitSet) WriteTo(stream io.Writer) (int64, error) {
 	buf := make([]byte, wordBytes)
 	length := uint64(b.length)
@@ -943,6 +950,13 @@ func (b *BitSet) WriteTo(stream io.Writer) (int64, error) {
 // it is extended. In case of error, the BitSet is either
 // left unchanged or made empty if the error occurs too late
 // to preserve the content.
+//
+// Performance: if this function is used to read from a disk or network
+// connection, it might be beneficial to wrap the stream in a bufio.Reader.
+// E.g.,
+//
+//	f, err := os.Open("myfile")
+//	r := bufio.NewReader(f)
 func (b *BitSet) ReadFrom(stream io.Reader) (int64, error) {
 	buf := make([]byte, wordBytes)