You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
The text was updated successfully, but these errors were encountered:
GitBook looks pretty. If we want, we can have it automatically mirror the content of a GitHub repo... if we do that, do we then have to edit via GitHub, or is it ok to edit via GitBook's prettier edit ui?
It would also be nice for LingView users to be able to access the docs offline. Maybe by having them be part of the code in the LingView repository, maybe through a "print docs to pdf" capability, maybe some other way. This is less important now that the recommended LingView workflow occurs mostly/entirely online in a browser.
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.
The text was updated successfully, but these errors were encountered: