Update docs readme

Trying to make the instructions even clearer
QutEcoacoustics · Feb 12, 2021 · ed27e98 · ed27e98
1 parent 79168e8
commit ed27e98
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 13 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -12,43 +12,51 @@ Ensure you have [Chocolatey installed](https://chocolatey.org/install). Then:
 choco install docfx -y
 ```
 
-To generate the docs:
+To generate the docs (from audio-analysis repo root):
 
 ```powershell
-../build/generate_docs.ps1
+./build/generate_docs.ps1
 ```
 
 Notes:
 
 - If there are any errors or warnings they need to be fixed before your changes are committed.
 - You **must rebuild** after changes to see the updated preview
 
-To preview (from audio-analysis repo root), run the _serve_ command in a separate terminal:
+To preview (from **audio-analysis repo root directory**), in PowerShell:
 
-```powershell
-cd _site
-docfx serve
-```
+1. Run the big build script first:
+    ```powershell
+    ./build/generate_docs.ps1
+    ```
+1. Run the quick build command after each change:
+    ```powershell
+    docfx build ./docs/docfx.json
+    ```
+1.  Run the _serve_ command in a _separate terminal_:
 
-Then visit the url in your browser, typically <http://localhost:8080>.
+    ```powershell
+    docfx serve ./_site
+    ```
+1. Then visit the url in your browser, typically <http://localhost:8080>.
 
 ## Layout
 
 The documentation is laid out into several areas:
 
-- **basics**: include introductory topics, like downloading, installing, and general bit of information
+- **basics**: include introductory topics, like downloading, installing, and general bits of information
 - **theory**: is reserved for pages discussing theory like:
     - how audio algorithms work
     - how noise removal works
     - what the indices are
     - how indices are calculated
     - which event detection algorithms we have
-- **guides**: short form workflows
+- **guides**: short form workflows which can be adapted to a user's usecase
     - if I have audio and I want a spectrogram I do ...
     - if I have audio and I want a FCS I do ...
     - if I have indices and I want FCS I do...
     - if I have segmented FCS/indices and I want them joined i do...
-- **tutorials**: Reserved for detailed lessons
+- **tutorials**: Reserved for detailed lessons, with specific working examples
 - **FAQ**: as you expect, duplicated in basics
 - **Articles**: news/blog posts etc
 - **Documentation**: is the _technical_ folder and hides anything that is too technical for general users
@@ -71,4 +79,4 @@ Use `../build/generate_docs.ps1` and then `../build/publish_docs.ps1.`
 
 Note the `NETLIFY_AUTH_TOKEN` environment variable must be defined.
 
-This file is not published with the docs.
+This file is not published with the docs.
diff --git a/docs/guides/generic_recognizers.md b/docs/guides/generic_recognizers.md
@@ -376,7 +376,7 @@ Some of these algorithms have extra parameters, some do not, but all do have the
 
 | I want to find a | I'll use this algorithm                                                                  |
 |------------------|------------------------------------------------------------------------------------------|
-| Shriek           | [!BlobParameters](xref:AnalysisPrograms.Recognizers.Base.BlobParameters) 🚧             |
+| Shriek           | [!BlobParameters](xref:AnalysisPrograms.Recognizers.Base.BlobParameters)                 |
 | Whistle          | 🚧 !HorizontalTrackParameters 🚧                                                        |
 | Chirp            | [!ForwardTrackParameters](xref:AnalysisPrograms.Recognizers.Base.ForwardTrackParameters) |
 | Whip             | 🚧!UpwardsTrackParameters 🚧                                                            |