Zeal Documentation

website·Indexed 29 days ago

https://zeal-docs.netlify.app

Internal documentation for Zeal, featuring frontend engineer onboarding checklists, environment setup prerequisites, documentation guidelines, and standards for ACL protection and FE-BE communication.

Tokens: 4.9K
Snippets: 38
Records: 45
Agent score: 75%

What's inside Zeal

Create a Process (Explanation) document
Process documents explain the 'how' and 'why' of a workflow to build understanding. They should include:
1. Overview: What the process covers.
2. The "Why": Rationale and context.
3. Detailed Process Flow: Step-by-step workflow.
4. Roles & Responsibilities: A mapping of who does what (often using a table).
5. Examples: Real-world scenarios.
```
# Process Title

## Overview
## Why This Process Exists
## Process Flow
## Roles & Responsibilities
| Role | Responsibility |
|------|---------------|
| Developer | [Action] |

## Examples
```
https://zeal-docs.netlify.app/docs/documentation-guidelines/
Create process flows with Mermaid diagrams
Use Mermaid syntax to embed process flows, architecture diagrams, or relationship maps directly in the documentation.
```
graph TD
    A[Start] --> B{Is authenticated?}
    B -->|Yes| C[Load Dashboard]
    B -->|No| D[Redirect to Login]
    C --> E[End]
    D --> E
```
https://zeal-docs.netlify.app/docs/documentation-guidelines/
Manage documentation versioning and changes
Use semantic versioning for documentation updates:
- Major (X.0.0): Breaking changes or fundamental rewrites.
- Minor (0.X.0): New sections or clarifications.
- Patch (0.0.X): Typo fixes and formatting.
Documents should include metadata (Version, Last Updated, Owner, Status) and a Change Log table for multi-version files.
```
:::info[Document Metadata]
| Field | Value |
|-------|-------|
| **Version** | 2.1 |
| **Last Updated** | January 15, 2025 |
:::

## Change Log
| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 2.1 | 2025-01-15 | Added OAuth2 flow | John Doe |
```
https://zeal-docs.netlify.app/docs/documentation-guidelines/
Handle ACL for Page Headers
If a page header contains only an Add/Create button and the user does not have the required control:{resource} permission, the entire header should be hidden using the useACL hook.
```
const { isAllowed } = useACL(['control:articles']);
if (!isAllowed) return null;
return <PageHeader><AddButton onClick={handleAdd} /></PageHeader>;
```
https://zeal-docs.netlify.app/docs/standards/acl-protection/
Create a Standard (Reference) document
Standards documents define hard rules for compliance and consistency. They must contain:
1. Rule/Standard: A clear statement of the requirement.
2. Rationale: Why the rule exists.
3. Examples: Explicit "Do" and "Don't" code snippets.
4. Enforcement: How the rule is checked or enforced.
```
# Standard Title

## The Rule
## Rationale
## Examples
### ✅ Do
```typescript
// Good example
```
❌ Don't
```
// Bad example
```
Enforcement
https://zeal-docs.netlify.app/docs/documentation-guidelines/

Add code examples to documentation

Code examples must include a language tag for syntax highlighting and comments to explain the logic.

// Good - Language specified, comments explain logic
interface User {
  id: string;
  email: string;
  role: 'admin' | 'user';
}

const createUser = (email: string): User => {
  // Generate unique ID
  const id = crypto.randomUUID();
  
  // Default role is 'user'
  return { id, email, role: 'user' };
};

Documentation maintenance checklist
Before merging a PR that affects documentation, verify the following:
- Writing style is second person and active voice.
- All code examples are tested and working.
- sidebars.ts is updated for new files.
- Obsolete information is removed.
- Version number, change log, and 'Last Updated' date are current.
- Internal links are functional.
- Heading hierarchy is correct.
- Code blocks have language tags.
- Frontmatter metadata is added.
https://zeal-docs.netlify.app/docs/documentation-guidelines/
Structure a Standards document
Standards documents define rules and provide clear examples of correct and incorrect implementations.
```
# Standard Title

## The Rule
[Clear statement]

## Rationale
[Why this exists]

## Examples

### ✅ Do
[Good example]

### ❌ Don't
[Bad example]
```
https://zeal-docs.netlify.app/docs/documentation-guidelines/example-documentation-page/
Handle file uploads in API requests
File uploads must be handled via a separate common file upload endpoint rather than within the main resource request.
Workflow:
1. Upload: The Frontend sends a POST request with the file to the upload endpoint. The Backend returns a UUID and URL for the uploaded file.
2. Reference: The Frontend then sends the file UUID as part of the main resource POST request.
```
sequenceDiagram
    participant FE as Frontend
    participant Upload as Upload Endpoint
    participant API as Main API

    FE->>Upload: POST /upload (file)
    Upload-->>FE: { uuid, url }
    FE->>API: POST /resource (uuid)
    API-->>FE: Success
```
https://zeal-docs.netlify.app/docs/processes/fe-be-communication/
Create and name documentation files
New documentation files must use the kebab-case naming convention. Avoid using PascalCase, snake_case, or spaces in filenames.
```
# Good
docs/guides/my-new-guide.md

# Bad
docs/guides/MyNewGuide.md
docs/guides/my_new_guide.md
docs/guides/my new guide.md
```
https://zeal-docs.netlify.app/docs/documentation-guidelines/example-documentation-page/
Structure a Process document
Process documents are used to describe workflows and responsibilities.
```
# Process Title

## Overview
[What this covers]

## Why This Process Exists
[Rationale]

## Process Flow
[Step-by-step workflow]

## Roles & Responsibilities
[Who does what]
```
https://zeal-docs.netlify.app/docs/documentation-guidelines/example-documentation-page/

Implement ACL for EmptyState Actions

The EmptyState component (title and subtitle) must always remain visible. Only the action button should be hidden based on permissions. Do not wrap the entire EmptyState component in an ACLBoundary.

const { isAllowed: hasControlPermission } = useACL(['control:articles']);

return (
  <EmptyState
    title="No articles"
    subtitle="Get started by adding your first article"
    {...(hasControlPermission && {
      action: {
        onClick: handleAdd,
        label: 'Add Article',
      },
    })}
    data={articles}
  />
);

Zeal Documentation

What's inside Zeal

❌ Don't

Enforcement