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

Research a better documentation system #51

Open
Sheeri opened this issue Oct 1, 2020 · 1 comment
Open

Research a better documentation system #51

Sheeri opened this issue Oct 1, 2020 · 1 comment
Labels
accessibility documentation Improvements or additions to documentation enhancement New feature or request hacktoberfest

Comments

@Sheeri
Copy link
Collaborator

Sheeri commented Oct 1, 2020

Currently the documentation is a jekyll site using markdown/html, blog posts, and the just-the-docs theme.

What we need:

  • Accessibility - images don't have alt tags, for example, but I'm sure there are tons of accessibility issues we're not thinking of.

  • Cross-documentation linking that does not break if a detail is changed (e.g. moved to a different category)

  • Easy separation of tracks - one for end-user documentation, and one for developer documentation

  • Multi-media support - at the very least, text formatting, images and gifs. Movie support is a plus

  • Something fully supported by github - the theme is not supported and every page build gives a warning.

  • Workflow capabilities - e.g. developers can take different paths, like building the foundation and then building charts, or building the foundation and then building the iOS app. Right now we are using different blog categories and blog post dates to order and separate the workflows, which is suboptimal.

  • Easy to update and contribute to - this is an open source project, after all! Changes may be rapid and we want to make sure we can update stale items.

Converting the documentation is a bigger project, and is blocked by this.

@Sheeri Sheeri added documentation Improvements or additions to documentation enhancement New feature or request hacktoberfest accessibility labels Oct 1, 2020
@ayushjainrksh
Copy link
Contributor

I think Docusaurus is a great alternative to look into. Most importantly because it can be extended using React.
Some websites that use Docusaurus:
https://reactnative.dev/
https://allcontributors.org/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
accessibility documentation Improvements or additions to documentation enhancement New feature or request hacktoberfest
Projects
None yet
Development

No branches or pull requests

2 participants