Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move the LingView wiki to its own repo #83

Open
sciepsilon opened this issue Apr 23, 2021 · 2 comments
Open

Move the LingView wiki to its own repo #83

sciepsilon opened this issue Apr 23, 2021 · 2 comments
Labels
enhancement hours or days Tasks that will take more than an hour, but less than 20 hours

Comments

@sciepsilon
Copy link
Member

sciepsilon commented Apr 23, 2021

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.

@sciepsilon sciepsilon added enhancement hours or days Tasks that will take more than an hour, but less than 20 hours labels Apr 23, 2021
@sciepsilon
Copy link
Member Author

I'm playing around with GitBook (which is not affiliated with GitHub). https://app.gitbook.com/@kalinda-pride/s/lingview-docs

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?

@sciepsilon
Copy link
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement hours or days Tasks that will take more than an hour, but less than 20 hours
Projects
None yet
Development

No branches or pull requests

1 participant