Epic: collect needed documentation

[fyliu]

Overview

This issue tracks the documentation that needs to be added and the issue/pr where they would've been helpful in. The intention is to make it easy to note any missing documentation without having to create the issue at the same time.

Action Items

• PR review guide: Add missing documentation to the PR review guide #419
• Django: How to combine migrations Add missing documentation on how to combine migrations in Django #421
• Git: How to quickly checkout a PR Add missing documentation on how to quickly checkout a PR #422
• Git: How to add a git alias Add missing documentation on how to add an alias in GitHub #423
• Django, Git: How to resolve migration conflict Add missing documentation on how to resolve migration conflicts #424
• Git: How to apply changes from one file to a different file Add missing documentation on how to apply changes from one file to another in GitHub #425
• Git: How to combine the last several commits into one Missing documentation about how to combine a series of GitHub commits into one commit #450
• Git: How to update the docker compose command
• Docker: How to use new syntax replacing docker-compose

Resources/Instructions

How to use

1. Add a new comment for each documentation item needed using a copy of this template

   ### What's needed
   
   - Description of what the missing documentation is about
   
   ### Draft (if written)
   
   - Link to external docs with instructions (if applicable)
   
   ### Where it's useful
   
   - Link to what prompted the need for this change/addition (if applicable)
   - Situation where this could be used
   
   ### Where to put this
   
   **contributing docs** should go in the `/docs/contributing/` folder or sub-folders:
   - **how to guides** --> `/docs/contributing/howto/`
   - **tutorials** --> `/docs/contributing/tutorial/`
   
   ### Audience
   
   - Who or what role needs to perform this action
   
   ### Tags
   
   - git, django, etc.
   

2. Add an action item here, linking to the comment below

3. Create an issue to add the documentation (can be done later by another person)

   • Then, hide the original comment and add the new issue # to the action item

4. Work on the documentation issue and check off the action item (can be done later by yet another person)

[fyliu]

The contributing docs should go inside the /docs/contributing/ folder or sub-folders

• howto guides --> /docs/contributing/howto/
• tutorials --> /docs/contributing/tutorial/

maybe temporary locations

• style guides --> `/docs/contributing/style/'
  • bash scripting guide (example contents below)
    • set env options for each script (what's most common, what they mean, how to use them)
    • don't leave debug output
  • new documentation page guide

[fyliu]

What's needed

A guide for creating a new documentation page

I'm not sure if this falls under "style guides" or "howto"

Draft

Tags

• add tags to each page (example tags, how it works, which ones are strongly recommended like)

Example tags

1. reader: one of "contributing-docs"/"client-docs"
2. type: one of "intro"/"howto"/"tutorial"/"style"
3. topic: up to 5 relevant from "git", "django", etc.

How to add them

create a front matters section at the top of the document like this:

---
tags:
  - contributing-docs
  - howto
  - git
---

File location

• directory structure

  ├── docs                                                                                                                                                                                                                                       
  │   ├── contributing                                                                                                                                                                                                                           
  │   │   ├── onboarding                                                                                                                                                                                                                
  │   │   ├── tutorials
  │   │   ├── howto
  │   │   ├── style
  │   │   └── tools
  │   ├── intro                
  │   ├── topics
  │   ├── tutorials                
  │   ├── howto                
  │   └── API                                                
  

• where to put the page

  graph LR
    B -->|contributing| contributing;
    B{contributing/client?} -->|client| client;
  
    subgraph contributing [contributing docs]
    direction LR
    C -->|onboarding| F[/docs/contributing/onboarding/];
    C -->|tutorial| D[/docs/contributing/tutorials/];
    C -->|how to| E[/docs/contributing/howtos/];
    C -->|style guide| G[/docs/contributing/style/];
    C{content type} -->|tools| A[/docs/contributing/tools/];
    end
  
    subgraph client [client docs]
    direction LR
    H -->|introductory| I[/docs/intro/];
    H -->|high level description| M[/docs/topics/];
    H -->|tutorial| J[/docs/tutorials/];
    H -->|howto| K[/docs/howto/];
    H{content type} -->|API| L[/docs/api/];
    end
  
  

  Loading

Voice and tone

• voice style (suggestion until we have a technical writer to figure this out)
  • howto guide: conversational tone - "you do this", "you'll see this"
  • tutorial: "we" tone. Think of it as a longer journey - "we need to set this up", "now we're finally done"
  • TBD

TBD

Where it's useful

Someone adding a new documentation page can reference this to make sure they're making use of all the available functionalities of the docs site and the documentation is like the rest of the documentation.

There's a comment asking where new docs pages should go. That's also included in this guide.

Audience

contributors, technical writers

Tags

howto, style guide, documentation

[shmonks]

@fyliu Do you think the guide for creating a new documentation page be best in Wiki or Mkdocs?

[fyliu]

@shmonks I was thinkin Mkdocs. Maybe it's helpful to keep it in the wiki until it's more stabilized?

Oh I see what you mean. This might be for non-developers as well. But this guide is for adding documentation to the Mkdocs site. So I'm thinking the writer will have Mkdocs running locally on their computer. But I guess the writer can also modify the text in GitHub's website and create the PR, which would automatically fix any syntax problems in the markdown, and then another writer can review and approve.

I think most of the howto guides actually needs someone with a developer background to go through them to make sure they produce the expected outcome.

What should be the process of working on an approving this type of work? Developer create the first draft and writer review and produce a final one?

[shmonks]

Yes, I imagine we'd want a review - via PR probably best, then we could assign it to whoever. It sounds like Mkdocs would be the best place to have this new guide, with a link to it from the wiki.

[fyliu]

Once this is created, then update the following template
https://github.com/hackforla/peopledepot/blob/main/.github/ISSUE_TEMPLATE/update-table.md

What's needed

• How to generate a database table definition

Draft

• adapted from a previous comment in Update Table: User #429

Note: These steps work only for this project's database running locally in Docker container.

Shorter way

1. Get table definition

   ./scripts/db.sh -c "\d <table_name>"
   

   Example table name: core_user

• (Optional) Get all table names

  ./scripts/db.sh -c "\dt"
  

Long way

1. Enter the database shell in the docker container

   ./scripts/db.sh
   

2. Get list of tables

   \dt
   

3. Get table definition

   \d <table_name>
   

Where the documentation needs to go

• /docs/contributing/howto/generate-db-definition.md

Where it's useful

• Update Table: User #429 needed a way to generate a schema table in text format.
• Other similar issues can also use this guide.
• Link to what prompted the need for this change/addition
• Situation where this could be used

Audience

• contributor, developer

Tags

• postgres, schema, database

[fyliu]

What's needed

• MD file syntax guide

Draft (very incomplete at the moment)

code block indentation

• if under a header, no indent
• if under a bullet line, indent entire block 3 or 4 spaces in GitHub, or 4 spaces in MkDocs markdown

lists

• bullet lists start with -. Standardizing so we don't have a mix of - and * bullets.
• numbered lists start with 1.. The numbers will be autogenerated by the markdown renderer.

Where it's useful

• a comment in Add missing documentation on how to quickly checkout a PR #422 contains code blocks not indented enough.
• This is useful for formatting markdown files in the GitHub and MkDocs site.

Where to put this

Most of the contents are for the MkDocs site, so /docs/contributing/howto/format-markdown.md
But some contents are useful for GitHub as well, so also should add a link from the Wiki.

Audience

• contributors

Tags

• markdown

[shmonks]

What's needed

• Add troubleshooting section for GitHub SSH keys (for first time users or new machine).

Draft (if written)

• Link to external docs with instructions (if applicable)
• see website team's contributing file for ssh info for new users https://github.com/hackforla/website/blob/gh-pages/CONTRIBUTING.md#27f-working-on-an-issue-6-handling-ssh-authorization-errors. Its possible that to make this available to our team, we may want to add it as a stand alone tutorial on the Engineering CoP wiki. Engineering wiki: https://github.com/hackforla/engineering/wiki/Resources

Where it's useful

• Link to what prompted the need for this change/addition (if applicable)
• Situation where this could be used

Where to put this

contributing docs should go in the /docs/contributing/ folder or sub-folders:

• how to guides --> /docs/contributing/howto/
• tutorials --> /docs/contributing/tutorial/

Audience

• Who or what role needs to perform this action

Tags

• git, django, etc.

[fyliu]

@shmonks
commenting on the SSH comment #378 (comment) above:
The website guide looks useful and has instructions for mac and windows.

There's benefits both for putting it in our own mkdocs vs. Engineering Cop. With the tabs widget in mkdocs, it would make the instructions look shorter (hiding the instructions for the other OS). But putting it in Engineering CoP wiki would centralize it for other teams to reference, which is also a plus.

I think the best scenario would be to put it in Engineering CoP in mkdocs. We'd need to set it up for them (which is quick, and a one time thing) and consider what, if any, maintenance they'll have to do to mkdocs other than just writing the documentation in markdown.

[del9ra]

What's needed

• After the recent Docker updates, we need to replace the hyphen with a space in commands starting with docker-compose in script files like run.sh and migrate.sh. The hyphen is no longer needed. I encountered an issue where the docker-compose command didn’t work when I ran ./scripts/buildrun.sh

Draft (if written)

https://docs.docker.com/compose/releases/migrate/

Where it's useful

• Modify db docker service to use the env file #437
• If someone tries to start Docker using the ./scripts/buildrun.sh command

Where to put this

https://hackforla.github.io/peopledepot/contributing/dev_environment/#install-docker
https://github.com/hackforla/website/blob/gh-pages/CONTRIBUTING.md#16-dev-setup-6-build-and-serve-the-website-locally
https://github.com/hackforla/website/blob/gh-pages/CONTRIBUTING.md#i-a-few-notes-regarding-docker

Audience

Backend developer

Tags

• git, django, etc.

[fyliu]

• After the recent Docker updates, we need to replace the hyphen with a space in commands starting with docker-compose in script files like run.sh and migrate.sh. The hyphen is no longer needed.

@del9ra What do you think about updating all the calls to use the new syntax in the scripts?

They made the change maybe 2+ years ago. But some recent updates starting maybe a year ago started breaking the docker-compose command.

[del9ra]

• After the recent Docker updates, we need to replace the hyphen with a space in commands starting with docker-compose in script files like run.sh and migrate.sh. The hyphen is no longer needed.

@del9ra What do you think about updating all the calls to use the new syntax in the scripts?

They made the change maybe 2+ years ago. But some recent updates starting maybe a year ago started breaking the docker-compose command.

@fyliu Up until now, when running ./scripts/buildrun.sh, I only had issues with run.sh and migrate.sh. But if you've run into the same problem with other scripts, then yes, it makes sense to update all the calls. By the way, I didn’t have any issues with docker-compose command last year. The problems only started this January.

[fyliu]

@fyliu Up until now, when running ./scripts/buildrun.sh, I only had issues with run.sh and migrate.sh. But if you've run into the same problem with other scripts, then yes, it makes sense to update all the calls. By the way, I didn’t have any issues with docker-compose command last year. The problems only started this January.

@del9ra not all newer versions will break it. Only some updated do. I've experience it twice before, starting maybe a year ago, but not currently.

[fyliu]

In response to my comment above about moving common documentation to Engineering CoP, since they're not working on adding engineering documentation to even their wiki, I guess we'll just have to add what our team needs in our own docs for now. We can reference the website wiki where it's helpful. Maybe we should also make a local copy of the original text just in case something happens to the source page.