openlibhums / openlibhums/memory-alpha

Version control of documentation on memory alpha

Open
#11 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement Priority medium size XL
Dominant language
Markdown
Stars
0
Forks
0
Avg merge
4d 14h
Merged PRs (30d)
2

Description

We currently host Janeway's end user documentation on readthedocs, together with the software's technical documentation, using rST. We've decided to re-write the guides in Markdown to make them more approachable to non-technical documentation contributors, for which this projects would be a suitable home.

There is the question of how we want to build the documentation, some key features we need to support are

  1. Versioning: It should be possible to host incremental versions of the documentation so that the end user can browse the guides for the exact version of Janeway they are using. The versioning system also allows Janeway to link directly to the right version of the documentation
  2. Search: Users need to be able to search the documentation, without getting results from other parts of the Janewway website. The search should also be scoped to the current version of the documentation. Pelican supports site search through an official plugin for search
  3. Editing workflow through GitHub: Contributors should be able to contribute to the documentation without needing to setup the build chain for pelican. Despite not having styling, they should be able to use just the Github interface. Joe configured the static assets on #5 so that the paths are consistent across the Github and the generated static pages.

Discussed solutions for versioning:

  1. Develop a pelican aware plugin: We could write a plugin for pelican that supports versioned documentation. It would require also configuring the search plugin, so that each version has a different search index. In this use-case, all versions of the documentation exist in the source
  2. Build multiple sites from the source: In this case, the documentation holds the source for all versions, however, we would tweak our build process to build each version of the documentation as its own site. It requires including and maintaining a navigation pane that exists across all versions, allowing the user to change the version of the page they are on.
  3. Use GitHub tags/branches for version control: With this approach, the source code contains only one copy/one version of the documentation. In order to build past versions of the docs, our build process would need to refer to the version control system to find the correct files. building a cross-version navigation system here is more tricky, because when adding a new version it needs to be made available to other versions in other branches.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the current Read the Docs setup and the proposed Pelican workflow, including the Pelican search plugin and the static-asset configuration from issue #5. Compare the three versioning approaches described in this issue. Done means a decided implementation supports versioned documentation, version-scoped search, and GitHub-based editing for non-technical contributors.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, markdown
Domain
build-system, documentation, search
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.