Adapt to use similar text as in https://github.com/Testably/Testably.…

…Abstractions/pull/835/files

README.md

@@ -156,33 +156,55 @@ public class SomeClassUsingFileSystemWatcher
   provides convenience functionality on top of the core abstractions.
 
 -   [`System.IO.Abstractions.Analyzers`](https://github.com/TestableIO/System.IO.Abstractions.Analyzers)
-  provides Roslyn analyzers to help use abstractions over static methods. 
-
--   [`Testably.Abstractions`](https://github.com/Testably/Testably.Abstractions)
-  provides alternative test helpers and additional abstractions.
+  provides Roslyn analyzers to help use abstractions over static methods.
 
 ## Relationship with Testably.Abstractions
 
-[`Testably.Abstractions`](https://github.com/Testably/Testably.Abstractions) is a complementary project that uses the same interfaces from [`TestableIO.System.IO.Abstractions`](https://www.nuget.org/packages/TestableIO.System.IO.Abstractions). This means **no changes to your production code are necessary** when switching between the testing libraries.
-
-### Key Differences and Features
-
-**Testably.Abstractions** offers more extensive testing helpers and features compared to this project:
-
-- **Advanced time handling** with `ITimeSystem` interface
-- **Random system abstractions** with `IRandomSystem` interface
-- **Drive management** with support for multiple drives and limited size simulation
-- **FileSystemWatcher** support for testing file system events
-- **SafeFileHandle** support for advanced file operations
-- **More comprehensive API** for complex testing scenarios
-
-### Migration Guide
-
-To switch from `TestableIO.System.IO.Abstractions.TestingHelpers` to `Testably.Abstractions.Testing`:
-
-1. **In your test projects**: Replace the reference to [`TestableIO.System.IO.Abstractions.TestingHelpers`](https://www.nuget.org/packages/TestableIO.System.IO.Abstractions.TestingHelpers) with [`Testably.Abstractions.Testing`](https://www.nuget.org/packages/Testably.Abstractions.Testing)
-2. **In your production code**: No changes needed! Both libraries use the same [`TestableIO.System.IO.Abstractions`](https://www.nuget.org/packages/TestableIO.System.IO.Abstractions) interfaces
-3. **In your tests**: Use the `MockFileSystem` from `Testably.Abstractions.Testing` instead
+[`Testably.Abstractions`](https://github.com/Testably/Testably.Abstractions) is a complementary project that uses the same interfaces as TestableIO. This means **no changes to your production code are necessary** when switching between the testing libraries.
+
+### When to use Testably.Abstractions vs TestableIO
+- **Use TestableIO.System.IO.Abstractions** if you need:
+  - Basic file system mocking capabilities
+  - Direct manipulation of stored file entities (MockFileData, MockDirectoryData)
+  - Established codebase with existing TestableIO integration
+
+- **Use Testably.Abstractions** if you need:
+  - Advanced testing scenarios (FileSystemWatcher, SafeFileHandles, multiple drives)
+  - Additional abstractions (ITimeSystem, IRandomSystem)
+  - Cross-platform file system simulation (Linux, MacOS, Windows)Expand commentComment on line R163ResolvedCode has comments. Press enter to view.
+  - More extensive and consistent behavior validation
+  - Active development and new features
+
+### Migrating from TestableIO
+Switching from TestableIO to Testably only requires changes in your test projects:
+
+1. Replace the NuGet package reference in your test projects:
+   ```xml
+   <!-- Remove -->
+   <PackageReference Include="TestableIO.System.IO.Abstractions.TestingHelpers" />
+   <!-- Add -->
+   <PackageReference Include="Testably.Abstractions.Testing" />
+   ```
+
+2. Update your test code to use the new `MockFileSystem`:
+   ```csharp
+   // Before (TestableIO)
+   var fileSystem = new MockFileSystem();
+   fileSystem.AddDirectory("some-directory");
+   fileSystem.AddFile("some-file.txt", new MockFileData("content"));
+
+   // After (Testably)
+   var fileSystem = new MockFileSystem();
+   fileSystem.Directory.CreateDirectory("some-directory");
+   fileSystem.File.WriteAllText("some-file.txt", "content");
+   // or using fluent initialization:
+   fileSystem.Initialize()
+       .WithSubdirectory("some-directory")
+       .WithFile("some-file.txt").Which(f => f
+           .HasStringContent("content"));
+   ```
+
+Your production code using `IFileSystem` remains unchanged.
 
 ### Architectural Differences