Merge pull request #33407 from rushatgabhane/readme

docs/README.md

@@ -65,14 +65,109 @@ The [docs](https://github.com/Expensify/App/tree/main/docs) folder will contain
 
 More details about the Jekyll project structure can be found [here](https://jekyllrb.com/docs/structure/). Note that all html files in this project support the use of the [liquid template language](https://shopify.github.io/liquid/).
 
+# Terminology
+- **Platform**: Expensify Classic and New Expensify are the two platforms. They are shown on the homepage.
+  - **Hub**: A hub is a collection of related articles. It comprises of:
+    - **Article**: The document that explains some feature.
+    - **Subcategory**: A narrower collection of related articles.
+
+To put it all together, this is the mental model that you should have.
+
+- Expensify Classic (Platform)
+  - Getting Started (Hub)
+    - Invite Members (Article)
+    - Security (Article)
+    - Playbooks (Subcategory)
+      - Small business guide (Article)
+      - Big business guide (Article)
+
+# How to create a new hub
+Let's assume that we want to create a new hub called Billing and Subscriptions inside the platform New Expensify.
+
+1. Open `docs/_data/_routes.yml`
+2. Under New Expensify add
+```
+    - href: billing-and-subscriptions
+      title: Billing & Subscriptions
+      icon: /assets/images/subscription.svg
+      description: Adjust billing...
+```
+3. Use an existing icon, or a new one by adding it to `docs/assets/images/`
+
+
+Link the hub.
+1. Go to `docs/new-expensify/hubs`
+2. Create a new folder using the hub name `billing-and-subscriptions`
+3. Inside the newly created folder, create `index.html` with the following content.
+```
+---
+layout: default
+title: Billing & Subscriptions
+---
+
+{% include hub.html %}
+``` 
+
+Add articles.
+1. Go to `docs/articles/new-expensify`
+2. Create a new folder with the hub name `billing-and-subscriptions`
+
+You are now ready to start adding articles and subcategories inside the hub 🎉
+
+# How to delete an existing hub
+Let's assume we want to delete the hub `integrations` inside the platform Expensify Classic.
+1. Open `docs/_data/_routes.yml`
+2. Find the hub integrations and delete its href, icon, title and description.
+3. Go to `docs/expensify-classic/hubs/`
+4. Delete the folder with your hub name and all its contents. eg: `integrations/`
+
+Delete all articles for the hub
+1. Go to `docs/articles/expensify-classic/`
+2. Delete the folder with your hub name and all its contents. eg: `integrations/`
+
+# How to rename a hub
+If you need help with how to do this on github. Follow this [slack thread 🧵](https://expensify.slack.com/archives/C02QSAC6BJ8/p1703012261896119?thread_ts=1702999732.847589&cid=C02QSAC6BJ8) in `#expensifyhelp`
+
+Let's assume that we need to rename the hub `get-paid-back` to `payments` for the platform `New Expensify`
+1. Go to `docs/new-expensify/hubs/`
+2. Rename the folder `get-paid-back/` to `payments`
+3. Go to `docs/articles/new-expensify/`
+4. Rename the folder `get-paid-back/` to `payments`
+5. Open docs/_data/_routes.yml 
+6. Rename the href `get-paid-back` to `payments`
+7. Change `title` to `Payments`
+
+# How to change icon of a hub
+1. Open `docs/_data/_routes.yml`
+2. Under the platform and hub, replace the icon link `assets/images/send.svg`.
+3. Use an existing icon, or a new one by adding it to `docs/assets/images/`
+
+# How to create a new subcategory
+Creating a new subcategory is as easy as creating a new folder. For example, if we want to create a new subcategory `HR Integrations` for the hub `Integrations` and platform `Expensify Classic`
+1. Go to `docs/articles/expensify-classic/integrations`
+2. Create a new folder `hr-integrations`
+
+You can now begin adding articles inside the subcategory `hr-integrations/`.
+
 # How to add a new Article
 
 ## Add content
 
-Copy the [template](https://github.com/Expensify/App/blob/main/docs/TEMPLATE.md) file into the correct subdirectory of `/articles`. For example, if the article belongs in the `Send money` hub and `Workspaces` section, then copy the template into `articles/send-money/workspaces` directory. Next, rename the copy with the name of the article title, i.e. [The-Free-Plan.md](https://github.com/Expensify/App/blob/main/docs/articles/send-money/The-Free-Plan.md) (you can use dashes for spaces in the file name if it's needed) and put the new file inside of the respective hub folder or sub-folder. The title will be rendered automatically according to the filename (the dashes will be removed in the generated site page).
+Copy the [template](https://github.com/Expensify/App/blob/main/docs/TEMPLATE.md) file into the correct subdirectory of `docs/articles`. For example, if the article belongs in the `Bank Accounts` hub for the platform `Expensify Classic`, then copy the template into `docs/articles/expensiyfy-classic/bank-accounts` directory.
+
+Next, rename the copy with the name of the article title, i.e. `Connect-ANZ.md`. It is **important** that the article has `.md` extension (you can use dashes for spaces in the file name if it's needed). The dashes will be removed in the generated site page. 
 
 The sections of the article will be filled and nested automatically in the LHN, just ensure to use the [heading markdown tags](https://www.markdownguide.org/cheat-sheet/) correctly.
 
+## Add images
+1. Drag and drop your image inside `docs/assets/images/`
+2. Use the image in your article by adding the markdown `![Image description here]({{site.url}}/assets/images/your_image_name_here.png){:width="100%"}`
+
+- Note to replace `your_image_name_here` with the name of image that you uploaded.
+- Note to replace `Image description here`  with an apt description of the image.
+
+If you're unfamiliar with github branches, PRs and confused how to add images and article in the same PR, head to this [slack thread 🧵](https://expensify.slack.com/archives/C02QSAC6BJ8/p1699632298177679?thread_ts=1699576284.768909&cid=C02QSAC6BJ8) in `#expensifyhelp`.
+
 ## Add meta-description tags for SEO
 
 At the top of template file we're going to find a few variables that will help us to define the meta-description of the article for SEO:
@@ -87,11 +182,14 @@ image: (Optional) URL to an image associated with the post, page, or document (e
 
 Just update the content for each variable accordingly or remove it if the information is not available. More details [here](https://github.com/jekyll/jekyll-seo-tag/blob/master/docs/usage.md#usage).
 
-## Add the new page to routes.yml
-
-Next, run the command `npm run createDocsRoutes` to add the article to `_data/routes.yml`. Note that hubs contain one or more articles, which may or may not be grouped into sections with other related articles. All articles grouped under a section will be under the same subfolder in the hub folder.
+# How to rename an article
+Assume that we want to rename the article `The Free Plan` to `Freemium Features` for the hub `billing and plan types` in New Expensify platform.
+1. Go to `docs/articles/new-expensify/billing-and-plan-types`
+2. Rename `The-Free-Plan.md` to `Freemium-Features.md`. Use dashes for spaces in the file name.
 
-If you have added a new hub, make sure to update the `_routes.yml` with the folder name, title, icon and description of the hub.
+Note: It is important that the file has `.md` extension.
 
 # How the site is deployed
-This site is hosted on GitHub Pages. GitHub Pages has a built-in Jekyll integration, and we have it configured such that whenever code is merged to main, GitHub will automatically build the Jekyll site housed in the `/docs` directory and deploy it straight to production. The help site is publicly discoverable at https://help.expensify.com/
+This site is hosted on Cloudflare pages. Whenever code is merged to main, the github action `deployExpensifyHelp` will run.
+
+It will generate routes.yml using the script `createDocsRoutes`, build the Jekyll site housed in the `/docs` directory and deploy it straight to production. The help site is publicly discoverable at https://help.expensify.com/

docs/TEMPLATE.md

@@ -1,10 +1,10 @@
 ---
 title: The title of the post, page, or document
-description: A short description of the page's content
+description: A short description of the page's content. This is used for SEO purposes
 ---
 <!-- The lines above are required by Jekyll to process the .md file -->
 
-# About
+# Overview
 <!--
 This short blurb provides all the context the user might need to know what the feature is and why they'd use it. If there are particular best practices embedded in the design, we'd explain why they're best practices here.
 
@@ -21,6 +21,16 @@ What options does a user have then interacting with this feature?
 What elements of this feature are pay-walled vs. free?
 -->
 
+# Deep Dive
+<!--
+This section will be the final nice-to-know section which covers additional Best Practices that apply to niche use-cases, alternate setup configurations, and in-depth details for parts of a feature that do not apply to all users. These will likely only be required for very complex features with high configurability.
+
+- Is the feature multi-layered (contains features within features) and needs further explanation in this section? Example: Managing Domains.
+- Does the feature have several different variables that can cause different outcomes for different customers? Example: Billing.
+- Does the feature have optional enhancements that can be used in different ways depending on the use case? Example: Category-specifc rules.
+-->
+
+
 {% include faq-begin.md %}
 <!--
 This section covers the useful but not as vital information, it should capture commonly queried elements which do not organically form part of the About or How-to sections.
@@ -33,12 +43,3 @@ This section covers the useful but not as vital information, it should capture c
  - Note: troubleshooting should generally go in the FAQ, but if there is extensive troubleshooting, such as with integrations, that will be housed in a separate page, stored with and linked from the main page for that feature.
 -->
 {% include faq-end.md %}
-
-# Deep Dive
-<!--
-This section will be the final nice-to-know section which covers additional Best Practices that apply to niche use-cases, alternate setup configurations, and in-depth details for parts of a feature that do not apply to all users. These will likely only be required for very complex features with high configurability.
-
-- Is the feature multi-layered (contains features within features) and needs further explanation in this section? Example: Managing Domains.
-- Does the feature have several different variables that can cause different outcomes for different customers? Example: Billing.
-- Does the feature have optional enhancements that can be used in different ways depending on the use case? Example: Category-specifc rules.
--->

docs/_data/_routes.yml

@@ -12,7 +12,7 @@ platforms:
     description: "Your account settings look like this:"
     image: /assets/images/settings-old-dot.svg
 
-    # Hubs are comprised of sections and articles. Sections contain multiple related articles, but there can be standalone articles as well
+    # Hubs are comprised of subcategories and articles. Subcategories contain multiple related articles, but there can be standalone articles as well
     hubs:
       - href: getting-started
         title: Getting Started