Developer Documentation Repository

Welcome to the Developer Documentation Repository! This repository is designed to house and organize project-specific developer documentation for your team. Each project's documentation resides in its designated folder, and this documentation is built with HonKit into a static site that can be hosted and shared for all developers to reference.

This README provides instructions on how to contribute, update, and structure documentation for each project in the repository.

Table of Contents

• Folder Structure
• Prerequisites
• How to Add/Update Project Documentation
• Building the Documentation
• Previewing the Documentation Locally
• Contributing Guidelines
• Example Usage

Folder Structure

The repository is organized into folders where each folder represents a project. Here's the structure you must follow:

root/
├── project-1/               # Folder for Project 1
│   ├── README.md            # Overview of Project 1
│   ├── api-reference.md     # API reference for Project 1
│   ├── setup-guide.md       # Setup and installation instructions
├── project-2/               # Folder for Project 2
│   ├── README.md            # Overview of Project 2
│   ├── database-guide.md    # Database documentation for Project 2
│   ├── troubleshooting.md   # Troubleshooting tips for developers
├── guidelines/              # Shared common documents and guidelines
│   ├── coding-standards.md  # Company-wide coding standards
│   ├── git-workflow.md      # Git branching and collaboration guidelines
├── README.md                # This README
├── SUMMARY.md               # Table of Contents for HonKit (defines navigation)
├── book.json                # HonKit configuration file

Naming Conventions

• Each project folder should follow this structure:
  • README.md: Contains a summary of the project and acts as the root of the folder.
  • Include specific documentation files, such as api-reference.md, setup-guide.md, or others as per your project's needs.
• Use dash-cased filenames for additional documentation (e.g., api-reference.md or setup-guide.md).
• Shared/global guides (coding standards, workflows, onboarding, etc.) belong in the guidelines/ folder.

Prerequisites

To contribute or modify this HonKit repository, you will need the following:

1. Node.js and npm:

   • Install Node.js version 18+ or higher.
   • Verify installation:

     node -v
     npm -v
     

2. HonKit CLI:

   • Install globally:

     npm install honkit@6.0.2 -g
     

3. Git: Clone the repository and make changes:

   git clone <your-repository-url>
   cd <repository-folder>
   

How to Add/Update Project Documentation

Follow these steps to label and update project-specific documentation:

1. Add a New Project

1. Create a new folder in the root directory with the project name:

   mkdir project-1
   

2. Inside the folder, create a README.md file and any additional docs (e.g., setup-guide.md, dev-notes.md):

   cd project-1
   touch README.md setup-guide.md dev-notes.md
   

3. Add content to the newly created markdown files:

   Example README.md:

   # Project 1
   
   ## Overview
   Project 1 is a backend microservice for handling payment transactions.
   

2. Update the SUMMARY.md File

Edit the SUMMARY.md to include your new project folder and documentation structure. This defines the table of contents and structure in the HonKit-generated site.

Example:

# Summary

* [Introduction](README.md)
* [Project 1](project-1/README.md)
  * [Setup Guide](project-1/setup-guide.md)
  * [API Reference](project-1/api-reference.md)
* [Project 2](project-2/README.md)
  * [Database Guide](project-2/database-guide.md)
  * [Troubleshooting](project-2/troubleshooting.md)
* [Project 3](project-3/README.md)
  * [Setup Guide](project-3/setup-guide.md)
  * [Developer Notes](project-3/dev-notes.md)
* [Guidelines](guidelines/README.md)
  * [Coding Standards](guidelines/coding-standards.md)
  * [Git Workflow](guidelines/git-workflow.md)

3. Test Your Additions

• See Previewing the Documentation Locally.

Building the Documentation

To build the documentation into a static website (outputs to _book/ folder):

honkit build

• The _book folder will contain the static HTML files ready for hosting.
• Ensure your changes build successfully without errors.

Previewing the Documentation Locally

To view your documentation locally in real-time during development:

1. Start the HonKit server:

   honkit serve
   

2. Open your browser and go to http://localhost:4000.

3. Validate your changes and ensure the structure is correct.

Contributing Guidelines

1. Branching Strategy:

   • Create a feature branch for updates or new projects:

     git checkout -b feature/project-1-docs
     

   • Push your branch and submit a pull request for review.

2. Markdown Style Rules:

   • Follow consistent Markdown conventions:
     • Use # for section headings.
     • Add meaningful titles and short, clear sections.
     • Use bullet points or numbered lists for clarity.
   • Provide code snippets with syntax highlighting if necessary:

3. Review Process:

   • All changes should be peer-reviewed via Pull Requests.
   • Ensure that changes are tested with honkit serve before submitting.

4. File Naming Conventions:

   • Use dash-case for filenames (e.g., setup-guide.md).
   • Avoid spaces or uppercase in filenames.

Example Usage

To document Project 1, you would:

1. Create a project-1 folder.
2. Add a README.md and other relevant Markdown files.
3. Add a link for it to SUMMARY.md.
4. Test locally with honkit serve.
5. Submit changes to the repository.