docs: refresh FAQ and migration guidance

docs/source/faq.md

@@ -4,83 +4,78 @@
 
 ### Do I need Python knowledge to use batdetect2?
 
-Not much. If you only want to run the model on your own recordings, you can
+Not much.
-use the CLI and follow the steps in {doc}`getting_started`.
+If you only want to run the model on your own recordings, you can use the CLI and follow the steps in {doc}`getting_started`.
 
-Some command-line familiarity helps, but you do not need to write Python code
+Some command-line familiarity helps, but you do not need to write Python code for standard inference workflows.
-for standard inference workflows.
 
 ### Are there plans for an R version?
 
-Not currently. Output files are plain formats (for example CSV/JSON), so you
+Not currently.
-can read and analyze them in R or other environments.
+Output files are plain formats (for example CSV/JSON), so you can read and analyze them in R or other environments.
 
 ### I cannot get installation working. What should I do?
 
 First, re-check {doc}`getting_started` and confirm your environment is active.
-If it still fails, open an issue with your OS, install method, and full error
+If it still fails, open an issue with your OS, install method, and full error output: [GitHub Issues](https://github.com/macaodha/batdetect2/issues).
-output: [GitHub Issues](https://github.com/macaodha/batdetect2/issues).
 
 ## Model behavior and performance
 
 ### The model does not perform well on my data
 
-This usually means your data distribution differs from training data. The best
+This usually means your data distribution differs from training data.
-next step is to validate on reviewed local data and then fine-tune/train on
+The best next step is to validate on reviewed local data and then fine-tune/train on your own annotations if needed.
-your own annotations if needed.
 
 ### The model confuses insects/noise with bats
 
-This can happen, especially when recording conditions differ from training
+This can happen, especially when recording conditions differ from training conditions.
-conditions. Threshold tuning and training with local annotations can improve
+Threshold tuning and training with local annotations can improve results.
-results.
 
 See {doc}`how_to/tune-detection-threshold`.
 
 ### The model struggles with feeding buzzes or social calls
 
-This is a known limitation of available training data in some settings. If you
+This is a known limitation of available training data in some settings.
-have high-quality annotated examples, they are valuable for improving models.
+If you have high-quality annotated examples, they are valuable for improving models.
 
 ### Calls in the same sequence are predicted as different species
 
-batdetect2 returns per-call probabilities and does not apply heavy sequence-
+Currently we do not do any sophisticated post processing on the results output by the model.
-level smoothing by default. You can apply sequence-aware postprocessing in your
+We return a probability associated with each species for each call.
-own analysis workflow.
+You can use these predictions to clean up the noisy predictions for sequences of calls.
 
 ### Can I trust model outputs for biodiversity conclusions?
 
-Use caution. Always validate model behavior on local, reviewed data before
+The models developed and shared as part of this repository should be used with caution.
-using outputs for ecological inference or biodiversity assessment.
+While they have been evaluated on held out audio data, great care should be taken when using the model outputs for any form of biodiversity assessment.
+Your data may differ, and as a result it is very strongly recommended that you validate the model first using data with known species to ensure that the outputs can be trusted.
 
 ### The pipeline is slow
 
-Runtime depends on hardware and recording duration. GPU inference is often much
+Runtime depends on hardware and recording duration.
-faster than CPU. If files are very long, splitting them into shorter clips can
+GPU inference is often much faster than CPU.
-help throughput.
-
-If you need a clipping workflow, see the annotation GUI repository:
-[batdetect2_GUI](https://github.com/macaodha/batdetect2_GUI).
 
 ## Training and scope
 
 ### Can I train on my own species set?
 
-Yes. You can train/fine-tune with your own annotated data and species labels.
+Yes.
+You can train/fine-tune with your own annotated data and species labels.
 
 ### Does this work on frequency-division or zero-crossing recordings?
 
-Not directly. The workflow assumes audio can be converted to spectrograms from
+Not directly.
-the raw waveform.
+The workflow assumes audio can be converted to spectrograms from the raw waveform.
 
 ### Can this be used for non-bat bioacoustics (for example insects or birds)?
 
-Potentially yes, but expect retraining and configuration changes. Open an issue
+Potentially yes, but expect retraining and configuration changes.
-if you want guidance for a specific use case.
+Open an issue if you want guidance for a specific use case.
 
 ## Usage and licensing
 
 ### Can I use this for commercial purposes?
 
-No. This project is currently for non-commercial use. See the repository
+No.
-license for details.
+This project is currently for non-commercial use.
+See the repository license for details.

docs/source/index.md

@@ -55,7 +55,7 @@ Then choose the section that matches what you need.
 If you are here mainly to run the model on recordings, start with Tutorials.
 
 | Section       | Best for                                      | Start here               |
-| --- | --- | --- |
+| ------------- | --------------------------------------------- | ------------------------ |
 | Tutorials     | Step-by-step routes for the most common tasks | {doc}`tutorials/index`   |
 | How-to guides | Answers to specific practical questions       | {doc}`how_to/index`      |
 | Reference     | Detailed command and settings help            | {doc}`reference/index`   |
@@ -82,6 +82,17 @@ Mac Aodha, O., Martinez Balvanera, S., Damstra, E., et al.
 _Towards a General Approach for Bat Echolocation Detection and Classification_.
 bioRxiv.
 
+or the bibtex entry
+
+```bibtex
+@article{batdetect2_2022,
+  title         = {Towards a General Approach for Bat Echolocation Detection and Classification},
+  author        = {Mac Aodha, Oisin and Mart\'{i}nez Balvanera, Santiago and Damstra, Elise and Cooke, Martyn and Eichinski, Philip and Browning, Ella and Barataudm, Michel and Boughey, Katherine and Coles, Roger and Giacomini, Giada and MacSwiney G., M. Cristina and K. Obrist, Martin and Parsons, Stuart and Sattler, Thomas and Jones, Kate E.},
+  journal       = {bioRxiv},
+  year          = {2022}
+}
+```
+
 ```{toctree}
 :maxdepth: 1
 :caption: Get Started

docs/source/legacy/migration-guide.md

@@ -80,10 +80,11 @@ prediction = api.process_file(Path("path/to/audio.wav"))
 
 Useful replacements:
 
-- legacy `process_file` -> current `BatDetect2API.process_file`
+- `batdetect2.api.process_file` -> current `BatDetect2API.process_file`
-- legacy `process_audio` -> current `BatDetect2API.process_audio`
+- `batdetect2.api.process_audio` -> current `BatDetect2API.process_audio`
-- legacy `process_spectrogram` -> current `BatDetect2API.process_spectrogram`
+- `batdetect2.api.process_spectrogram` -> current
-- legacy one-off batch loops -> current `process_files` or CLI `process`
+  `BatDetect2API.process_spectrogram`
+- one-off batch loops -> `BatDetect2API.process_files` or CLI `process`
 
 ### Model changes