Documentation Guide
Welcome to the Open Library documentation guide. Whether you're searching for information related to Solr or wondering where to contribute new content, this document provides a comprehensive overview of our documentation sources and guidelines.
Contributing to Open Library Documentation
- Include an appropriate heading at the top each document like
# Documentation Guide. This is necessary for better search. - The sidebar is generated based on the file location, so make sure to place your documentation in the correct folder.
index.md's first heading will be the name down in the sidebar for the parent folder.
Via the Web Interface
- Visit the Open Library GitHub Wiki.
- Find the file you want to edit, and click the Edit button on the top right-hand corner of the page.
- Make your changes, describe them in the Commit changes section at the bottom of the page, and click Save.
Editing Documentation Locally
If you're using advanced features like embedding videos, you'll want to use this method instead of editing in the web interface.
- Clone the Open Library wiki repository:
git clone https://github.com/internetarchive/openlibrary.wiki.git. - Install the pre-commit hooks:
pre-commit install. - Install the dependencies:
npm i, and start the documentation server:npm run docs:dev. - Open your web browser and navigate to http://localhost:5173 to view the documentation.
- Once you've finished making changes, commit them:
git commit -m "<your commit message>".
Search for Documentation
When looking for information within Open Library's documentation, you have several options.
Lets look at some example to search for "solr":
| Location | Description |
|---|---|
| Docs Site | Your starting point for documentation. Most guides and instructions are here. |
| Codebase | Markdown docs found directly in the source code. |
| GitHub Repository | Search PRs, Issues, Commits, etc to see how and why things were changed. |
| Internet Archive's GitHub org | Related repos: open-library-client, openlibrary-bots, openlibrary-librarians |
| Google Docs | Find community call notes, project briefs, and discussions. |
| OpenLibrary.org pages | OL homepage, help pages, etc. |
| blog.openlibrary.org | Announcements and big changes |
| Internet Archive videos | Watch tutorials and tours for a hands-on overview. |
| Slack | Search for archived discussions and troubleshooting tips. |
Where to Contribute New Content
| Criteria | Recommended Contribution Location |
|---|---|
| Content closely related to code or technical operations | Within the Open Library repository |
| Content focused on readers of Open Library (e.g. editions vs works) | openlibrary.org |
| Content related to onboarding, how things work, etc. that is relevant to technical contributors | GitHub Wiki |
| Content that requires collaboration between multiple stakeholders | Google Docs |