Merge pull request #1 from pietrop:readme-update

updated readme info

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: 
+
+---
+
+**Describe the bug**
+<!-- A clear and concise description of what the bug is. -->
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+<!-- A clear and concise description of what you expected to happen. -->
+
+**Screenshots**
+<!-- If applicable, add screenshots to help explain your problem. -->
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+<!-- Add any other context about the problem here. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: Enhancement
+assignees: 
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
+
+**Describe the solution you'd like**
+<!-- A clear and concise description of what you want to happen. -->
+
+**Describe alternatives you've considered**
+<!-- A clear and concise description of any alternative solutions or features you've considered. -->
+
+**Additional context**
+<!-- Add any other context or screenshots about the feature request here. -->

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,10 @@
+---
+name: Question
+about: Ask a question about this project
+title: ''
+labels: bug
+assignees: 
+
+---
+
+<!-- _where applicable, please provide context and use case around your question._ -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+**Is your Pull Request request related to another issue in this repository ?**      
+<!-- _If so please link to other issues and PRs as appropriate_ -->
+
+**Describe what the PR does**    
+<!-- _A clear and concise description of what the PR does. Feel free to use bulletpoints and checkboxes if needed [...]_ -->
+
+
+**State whether the PR is ready for review or whether it needs extra work**    
+<!-- _If you are still working on it and just setting it up for later review, or if it's ready to be reviewed for merging_ -->
+
+**Additional context**    
+<!-- Add any other context or screenshots about the PR. -->

README.md

@@ -2,6 +2,58 @@
 
 Experiments in converting YT subtitle formats to a JSON transcript with word-level timings.
 
-Run `npm install` or `yarn`, then `make`.
+<!-- _One liner + link to confluence page_
+_Screenshot of UI - optional_ -->
 
-Requires node >= 12 and youtube-dl.
+## Setup
+<!-- _stack - optional_
+_How to build and run the code/app_ -->
+
+git clone, cd into repo
+
+Run `npm install` or `yarn`,
+
+## Usage
+
+run `make`
+
+## System Architecture
+<!-- _High level overview of system architecture_ -->
+### ytdl subtitles and automatic captions formats 
+ytdl can get subtitles or automatic captions in several formats: ttml, vtt, srv1, srv2, srv3; the 1st ytdl in the makefile tries to get srv3/ttml/vtt as preference order; the rest of the ytdl forces to get also ttml and vtt just to have something to test the conversion on the conversion script converts from srv3, ttml or vtt.
+
+
+But from YT STT only srv3 and vtt has word timing, for now I process the real word timing only fron srv3, all the other ttml or vtt gets interpolated.
+
+With youtubedl, you don't know if you always have srv3. So it falls back to the other formats. the precedence is srv3/ttml/vtt.
+
+### non word level timing
+Now, on the non-word-level timing, the timings per line overlap because stuff is displayed in 2 lines that shift up.
+
+Basically I have to discard the end times for each line and set them to the start of the next line then I interpolate words.
+
+I think I can fix the repetition, then next is to lift the timecodes for the words, it won't be in all the words; then most likely use stt-align-node to spread that to the rest of the words.
+
+## Development env
+ <!-- _How to run the development environment_
+_Coding style convention ref optional, eg which linter to use_
+_Linting, github pre-push hook - optional_ -->
+
+- Requires node >= 12 
+- youtube-dl.
+
+## Build
+<!-- _How to run build_ -->
+
+_NA_
+
+
+## Tests
+<!-- _How to carry out tests_ -->
+
+_NA_
+
+## Deployment
+<!-- _How to deploy the code/app into test/staging/production_ -->
+
+on npm, _TBC_