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 Adding 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 Add missing documentation about how to combine a series of GitHub commits into one commit #450

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