Currently, the LingView docs are on the BrownCLPS/LingView wiki. That's where users should go to troubleshoot, for instructions setting up LingView, or for other info like what metadata LingView can display.
We should consider moving this content to a different location.
Benefits of the current location:
- clearly associated with the latest standard version of LingView software, since it's in the BrownCLPS/LingView repo
- doesn't get mixed up with LingView's code, since it's not actually in the repo
- right permissions (world-readable, and you can edit it iff you can edit LingView)
- each page has an edit history
- multiple pages with links between them, and the ability to link to specific sections of pages
- easily use headers, bold text, and tables (via Markdown), without complex style/layout decisions
- edit in the browser and publish immediately
Drawbacks of the current location, which I hope we could fix by moving the docs to a new location:
- when changing the user-facing title of the page, its edit history is irretrievably lost
- when changing the user-facing title of the page, you break all the links to that page
- can't organize pages hierarchically
- can't have multiple canonical versions of a page (Idk if that would actually be useful for us, but... some docs sites have a "what version of the product are you using?" dropdown in the top right, and I covet it.)
- no "staging area" for saving changes that you aren't ready to release to the public
The plan: Move the docs out of this repo's wiki, and put them as code in their own BrownCLPS/LingView-docs repo. Each page becomes an .md file, so we can keep the existing formatting. These can be organized into folders, renamed while preserving history (but not links), and developed via feature branches. GitHub pages isn't strictly necessary for the docs wiki, because GitHub already displays .md files nicely when you browse to them, but we can use it to give us a more streamlined layout. We can set the BrownCLPS/LingView-docs repo up with organization-level permissions so that it can automatically be edited by whoever can edit BrownCLPS/LingView code.
We can also consider something like GitBook to make the docs fancier.
When moving the docs, leave both copies in place temporarily until we're sure the new copy works. Then replace each old wiki page's content with an informative "this page has moved" notice.
Currently, the LingView docs are on the BrownCLPS/LingView wiki. That's where users should go to troubleshoot, for instructions setting up LingView, or for other info like what metadata LingView can display.
We should consider moving this content to a different location.
Benefits of the current location:
Drawbacks of the current location, which I hope we could fix by moving the docs to a new location:
The plan: Move the docs out of this repo's wiki, and put them as code in their own BrownCLPS/LingView-docs repo. Each page becomes an .md file, so we can keep the existing formatting. These can be organized into folders, renamed while preserving history (but not links), and developed via feature branches. GitHub pages isn't strictly necessary for the docs wiki, because GitHub already displays .md files nicely when you browse to them, but we can use it to give us a more streamlined layout. We can set the BrownCLPS/LingView-docs repo up with organization-level permissions so that it can automatically be edited by whoever can edit BrownCLPS/LingView code.
We can also consider something like GitBook to make the docs fancier.
When moving the docs, leave both copies in place temporarily until we're sure the new copy works. Then replace each old wiki page's content with an informative "this page has moved" notice.