Git Product home page Git Product logo

docs's Introduction

Branch Docs

Repository for Branch's public documentation https://docs.branch.io

Goal

  • Get partners up and running as fast as possible

    • Educate with a single best path (do not list all the override methods)

    • Educate with working code examples

    • Bullet point key points, procedures, and steps to promote progression

    • Use shorter sentences with simpler words (3rd grade) to prevent ambiguity

    • Trigger action by beginning each sentence with a verb

    • Write in the viewpoint of the user's wants, not what Branch wants

    • Keep it simple (KISS) (1 -> 2 -> 3)

    • Don't repeat yourself (DRY) (this can be found here)

  • Answer any question a partner will have

    • Make sure you answer why, what, how (example) with each section

Environment

  • Code

    git clone [email protected]:branchmetrics/docs.git
    cd docs
  • Dependencies

    pip install -r requirements.txt
  • Develop

    mkdocs serve
    open http://127.0.0.1:8000
  • Deploy

    • Merge pull request into master
    • Create new pull request from master
    • Merge pull request from master into production on release days
  • Production

Contributing

  • Folders

    • Must be lowercase and hyphened
  • Content

    • Bullets and sections must have double new line spacing in between

    • Indention is 4 spaces

    • Search works best when content is not duplicated

    • Only add periods if more than one sentence

  • Style

    • Titles # Title

    • Sections ## Section

    • Category - #### Section

    • Content - content

  • Code Tabs

    • Tabbed sections *title*, code, *title*, code
  • Navigation

    • Different page click [here](/apps/ios/) (must have trailing slash)

    • Different page anchor click [here](/apps/ios/#configure-bundle-identifier)

    • Same page anchor click [here](#configure-bundle-identifier)

  • Tips, notes, warnings etc.

  • Code Modals

    • Complete [Integrate your app](#dialog-code?ios=create-deep-link&android=install-branch)

    • Complete [Integrate your app](#dialog-code)

    • ios, android, cordova, mparticleAndroid, mparticleIos, titanium, reactNative, unity, xamarin

  • Images

    • Content pages are kept in the _assets/img/pages

    • Example images used in ingredients are kept in the _assets/img/ingredients

    • ![image](http://i.imgur.com/dyfhN0L.png)

  • Search

    • Hosted by Algolia Docsearch

    • Localhost scrapes production

    • Production is scraped once a day

    • Prevent search results by adding production url to stop_urls (config)

  • Redirection

    • Add redirect: /dashboard/people-based-attribution/ to the top of the file/

Additional

  • Resources

  • Mkdocs Locally

  • Mkdocs Fix

    • remove mkdocs sudo rm -rf /usr/local/bin/mkdocs

    • remove mkdocs link rm -rf /Library/Python/2.7/site-packages/mkdocs.egg-link

    • remove pip rm -rf /Library/Python/2.7/site-packages

    • reinstall pip curl https://bootstrap.pypa.io/get-pip.py > a.py && chmod -x a.py && sudo ./a.py

    • reinstall dependencies

    • run develop

  • Mkdocs-Material Locally

    • readme http://squidfunk.github.io/mkdocs-material/customization/#theme-development

    • add to repo git subtree add --prefix lib/mkdocs-material https://github.com/squidfunk/mkdocs-material master --squash

    • update to repo git subtree pull --prefix lib/mkdocs-material https://github.com/squidfunk/mkdocs-material master --squash

    • test live update in /materials

    • prod code in /src

      • cd lib/mkdocs-material

      • yarn install

      • yarn build (will build /material, but fail on /site (this is okay))

    • updated files

      • lib/mkdocs-material/src/partials/footer.html

      • lib/mkdocs-material/src/partials/header.html

      • lib/mkdocs-material/src/partials/search.html

      • lib/mkdocs-material/src/partials/nav.html

      • lib/mkdocs-material/src/base.html

      • lib/mkdocs-material/src/assets/javascripts/application.js

      • lib/mkdocs-material/src/assets/images/favicon.png

  • Slow page render

    • The docs should load within 1400ms. If it takes 5000ms, please disable Ghostery (Google Analytics) and Adblocker (the docs have AB testing)
  • Missing search

    • Some ad blockers prevent the search from appearing

docs's People

Contributors

aaaronlopez avatar aaustin avatar aeromusek avatar agrimn avatar amruta-d avatar bharath31 avatar chang-brian avatar code-crusher avatar derrickstaten avatar ethanneff avatar geneshay avatar gfletcher-branch avatar haiyinwang avatar igonebnyy avatar jackiechoi avatar jdee avatar kpoleyeff avatar lilabjorg avatar mikekwon36 avatar neilbranch avatar parthkalavadia avatar rahulchidanand1107 avatar rubinsingh avatar sarkar avatar sojanpr avatar themarshal99 avatar willbooz avatar wlindemann avatar xianc avatar zhukn1 avatar

Stargazers

 avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.