Merge pull request #708 from hapifhir/conversion-doc-update-2022-01

Conversion doc update 2022 01

org.hl7.fhir.convertors/README.md

@@ -1,6 +1,15 @@
 # Resource Conversion
 
-##### Let's talk about converting resources between the various versions of FHIR...
+## IMPORTANT
+-----
+
+_The conversion code in this module is maintained as part of the development of the standard, but always under 
+considerable time pressure. Only part of the code is rigorously tested [as detailed here](#reliable-conversion-code). 
+Implementers should regard this code as a 'scaffold' for actual reliable conversions._
+
+**ALWAYS TEST ANY CONVERSION ROUTINES BEFORE USING THEM IN PRODUCTION!**
+
+_Ideally, this should be via unit tests in your code, or better yet [unit tests contributed to FHIR](#test-cases)._
 
 ### A note regarding syntax
 
@@ -31,7 +40,7 @@ and [r4](http://hl7.org/fhir/R4/account.html)
 **N.B.** This information is only for code navigation purposes. It is important that when converting between versions 
 you use the provided conversion factory classes as your entry point.
 
-### Using the conversion library
+## Using the conversion library
 
 -----
 The majority of use cases for conversion will involve using the provided VersionConvertorFactory_V1_V2 classes to convert
@@ -193,3 +202,31 @@ Once you've created your new advisor, they can be provided as an argument when c
 `public static (V1 Resource) convertResource((V2 Resource) src, <T extends BaseAdvisor> advisor)`
 
 `public static (V2 Resource) convertResource((V1 Resource) src, <T extends BaseAdvisor> advisor)`
+
+## Development notes
+-----
+
+### Reliable conversion code
+
+The FHIR project maintains and tests conversions on the following resources, from old versions to R5:
+
+- CodeSystem
+- ValueSet
+- ConceptMap
+- StructureDefinition
+- StructureMap
+- ImplementationGuide
+- CapabilityStatement
+- OperationDefinition
+- NamingSystem
+
+These can be relied on and are subject to extensive testing.
+
+### Test cases
+
+Some conversions have test cases for particular resources and particular version combinations. Where test cases exist, 
+they will continue to be maintained and expected to pass.
+
+Contributing test cases is highly encouraged! To contribute, create a PRs to the 
+[core library](https://github.com/hapifhir/org.hl7.fhir.core), or even better, to the 
+[FHIR test cases library](https://github.com/FHIR/fhir-test-cases).

org.hl7.fhir.convertors/readme.md

@@ -1,32 +0,0 @@
-About the version conversion routines
-
-The version conversion routines are maintained as part of 
-the development of the standard, but always under considerable
-time pressure. Implementers should regard these as 'scaffolds' for 
-an actual reliable conversion routine. 
-
-The FHIR project maintains and tests conversions on the following 
-resources, from old versions to R5:
-* CodeSystem
-* ValueSet
-* ConceptMap
-* StructureDefinition
-* StructureMap
-* ImplementationGuide
-* CapabilityStatement
-* OperationDefinition
-* NamingSystem
-
-These can be relied on and are subject to extensive testing. 
-
-In addition to this, some of the conversions have test cases 
-for particular resources and particular version combinations. 
-Where test cases exist, they will continue to pass and be 
-maintained. 
-
-So:
-* test the conversion routines before using them in production
-* contribute test cases to ensure that your use cases continue to be reliable
-
-Test cases are welcome - make them as PRs to the core library, or even better,
-to the FHIR test cases library