SAP / SAP/spartacus-docs

DOC: GitHub Pages Doc Site To Do List

Open
#102 0 comments 0 reactions 1 assignee View on GitHub

@gladius-mtl is already working on this.

Since Jun 7, 2019.

Dominant language
HTML
Stars
11
Forks
22
Avg merge
7d 3h
Merged PRs (30d)
2

Description

These are some of the remaining tasks, in no particular order, to get the Spartacus GitHub Pages doc site up-and-running and ready for contributions:

  • Create include for tech reqs (which are repeated across several pages)
  • Test setting default permalink variables, see https://talk.jekyllrb.com/t/using-permalink-template-varaibles-on-pages/1406
  • Figure out behaviour of PRs in doc repo — people should by default send PRs to develop. Then, on lib release day develop gets merged to master (initial tests didn't seem to behave this way, so some testing still required here)
  • Need Contributing to Docs instructions for developers
  • Publish all recent updates for beta
  • Make the Contributing doc part of site — rather than pointing to the doc in our spa repo (so users stay within the doc site -- it's jarring to be shot out somewhere else without expecting it)
  • Update docs in spa repo to point to new gh pages site
  • Publish our latest auto-generated facade docs as part of the doc site -- also link to zips in release, mentioning how they are dependent on the version they're released with
  • Add links to docs repo and also to spa repo (top nav or FAQ or... ? Need to be easy to find)
  • Need Contributing to Docs instructions for writers (some pre-reqs to mention: github id, vs code, jekyll --> writers need to run their own builds to make sure they aren’t breaking anything (such as links) when they contribute docs)
  • Move docs archive (install doc archive) over to docs (pages) repo
  • Change target of top nav link “Installing Spartacus” — maybe add installing landing page somewhere and link to it<-- top nav updated to include just "Version 1.0 Beta" that points to release 1.0 page
  • Break Customizing CMS Components into two pages (ref: Bill’s proposed doc structure: https://wiki.hybris.com/display/spar/Doc+Hierarchy+for+1.0)
  • Adjust size of text in main content (currently too big -- but it is dynamic based on breakpoint, so some care is needed with the tweaking)
  • Adjust spacing between sidebar and main content (other changes to main text took care of this)
  • Fill in missing landing pages:
    • Extending Spartacus Features
    • User Experience Guidelines
    • Styling and Page Layout
  • Global Variables missing content
  • Configurable Routing missing content
  • Global Configuration in Spartacus needs a parent page (currently doesn’t exist), so add that page, and then move Global Configuration in Spartacus to child page (ref: Bill's proposed doc structure: https://wiki.hybris.com/display/spar/Doc+Hierarchy+for+1.0)
  • Investigate adding automatically visible anchor links, see: http://blog.parkermoore.de/2014/08/01/header-anchor-links-in-vanilla-javascript-for-github-pages-and-jekyll/
  • Add license and take care of other steps to make repo public
  • Search and replace extandable for extensible.

Contributor guide

Open the contributing guide

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.