0007 - Documentation convention¶

Overview¶

Documentation is the way to interactive within the team and within the organization

Space for convention in documentation for project

For the developer, should be:

Write documentation about usage within function, class
Write documentation about changelog
Write documentation about PR using template

Convention to follow¶

For reference to user in documentation. Use site:<PATH> for reference internal documentation for this site

- [@bao.truong](site:member/bao.truong)

For reference to internal documentation itself. There are 2 ways:

#### Endpoint: `/stock/detail` {id=e-stock-detail}

For icon: use fontawesome
For extension: follow documentation at Pymarkdown Extension
For filename related to product: using snake-case-with-hyphen-dashed.md style
For the context diagram, using the mermaid

Detail instruction¶

The group of enumration:

Please group in the following order: [FEATURE], [BUGFIX], [DOCS], [MAINTENANCE]

Format

Some example from the groud

# From GreateExpectation

# [FEATURE] Add Agent action to list table names in SQL Datasources (#8177)
# [FEATURE] Add Test Draft Config Workflow to Agent (#8410)
# [FEATURE] add run checkpoint action to agent (#8449)
# [FEATURE] DataAssistantResult should include exceptions from rules (#8429)
# [BUGFIX] Cleanup aws_postgres reference environment (#8439)
# [BUGFIX] Use consistent name between compose and cli command (#8440)
# [BUGFIX] Scaffolding .gitignore should not require writeable file system (#8362) (thanks @ivanstillfront)
# [BUGFIX] Remove unused, overwritten pytest marker. (#8441)
# [BUGFIX] get_validator throws AttributeError: 'CloudDataContext' object has no attribute 'ge_cloud_mode' (#8433)
# [BUGFIX] PP-282: fixing update_datasource method bug (#8464)
# [BUGFIX] Add performance marker to pyproject.toml (#8480)
# [BUGFIX] Fix Postgres, Trino quoted identifier issues (#8442)

Review, PR template

Using for dev to make the process to PR easiler

Code Reviews Should Not Suck!

Documentaion¶

For markdown syntax:

For math syntax: using Katex or Math https://katex.org/docs/supported.html

Write PR

For developers/maintainers/..., please contributes with more details elements.

E.g: Idea - Short introduction about your ideas - Label [Feature/Issues/Enhance] - ref URL.

You can use the icon to beautiful the element on https://gist.github.com/rxaviers/7360908

For Writer¶

Cool resources of how to write API documentation¶

[1] Schema.org URL

Some API documents is very attractive to follow¶

Name	URL
outline Developer	API Document URL

Documentaion¶

For markdown syntax:

For math syntax: using Katex or Math https://katex.org/docs/supported.html

Write PR

For developers/maintainers/..., please contributes with more details elements.

E.g: Idea - Short introduction about your ideas - Label [Feature/Issues/Enhance] - ref URL.

Source Reference¶

https://docs.greatexpectations.io/docs/contributing/contributing_checklist