Skip to content

Proposal to make LoopBack documentation open source

Jump to bottom
Rand McKinney edited this page Jul 12, 2016 · 11 revisions

Issue

LoopBack docs are currently hosted in Confluence, and this prevents the open-source community from editing the documentation directly. Because LoopBack is an open-source project, the docs should also be open source.

Proposed solution

Move doc content from Confluence into this repository (https://github.com/strongloop/loopback.io), to enable public contributions/editing. Publish the docs to http://loopback.io/doc. Existing content on http://loopback.io would remain (essentially) unaffected.

It makes sense to time this move to coincide with LoopBack 3.0. Then, the "new" OS docs would then reflect the most recent version, and the existing docs on Confluence would be "frozen" to reflect v. 2.0 (as well as legacy 1.x docs).

As part of this migration, it may make sense to review branding of the docs: do we want to retain the "StrongLoop" branding or rebrand them as simply "LoopBack" in keeping with the open-source nature of the project? See logos on http://loopback.io/resources/.

High-level tasks

  1. Create navigation framework similar to existing LH nav. Ideally, nav content would be sourced as nested lists in markdown and provide a nice "expandable" navigation widget. Task: https://github.com/strongloop/loopback.io/issues/28.
  2. Migrate content from Confluence to markdown. See Migrating LoopBack Docs to Markdown for use with Jekyll for details. Task: https://github.com/strongloop/loopback.io/issues/29.
  3. Figure out how to deal with content that we currently "transclude" (dynamically include) from other GitHub repos. Typically, these are example repo README files. We use a special Confluence macro to "single source" this content; we can do something similar with a Jekyll plugin, but there are wrinkles. Task: https://github.com/strongloop/loopback.io/issues/30.
  4. Use Google Custom Search to provide basic search functionality (see https://docs.strongloop.com/display/APIC/Search+LoopBack+docs). Task: https://github.com/strongloop/loopback.io/issues/31
  5. Review branding of new site (StrongLoop vs. LoopBack).
  6. Create Confluence macro to link from (old) Confluence pages to corresponding/new loopback.io pages.
  7. Publicize/socialize new site to encourage community participation.

Open issues

LooBack 2.x docs

At a minimum, we should move docs for LoopBack 3.0+, but what about LoopBack 2.x docs? We can either:

  • "Freeze" LB 2.0 docs as-is in Confluence, and maintain the existing docs.strongloop.com site until we fully deprecate LB 2.0.
  • Move LB 2.0 docs as well into this repo. In general, we don't spend much time or effort updating docs for old versions of LoopBack or Express. However, this might allow us to "retire" the Confluence server on docs.strongloop.com sooner.
Clone this wiki locally