Why Update Node Documentation?

Full Guide to Updating Your Node’s Documentation

Why Update Node Documentation?

Maintaining thorough and up-to-date documentation for your Core Lightning (CLN) node is essential for troubleshooting, auditing, and ensuring consistent operation. A detailed record helps track changes, configurations, and updates, making it easier to manage the node, debug issues, and understand past decisions.

1. How to Keep a Record of Configurations, Changes, and Optimizations

No CBDC

Method 1: Use a Changelog

A changelog is a file where you document the changes made to the node over time. It includes version changes, bug fixes, new features, and any configuration adjustments.
The changelog should follow a consistent format, so it’s easy to reference and track over time.

Example changelog entry:

## v0.11.1 (2025-01-24)
- Updated Core Lightning to version 0.11.1
- Rebalanced channels after liquidity adjustments
- Closed inactive channel `abc123456` (channel was underperforming)
- Added new channel with `xyz789012`

Make Privacy Great Again

Method 2: Personal Knowledge Base (Digital Notepad, Wiki, or Notion)

Maintain a digital knowledge base where you record detailed notes on configurations, commands run, and decisions made. This method allows for rich content, categorization, and linking to relevant resources.
Platforms like Notion, Google Docs, or Markdown-based wikis (e.g., Obsidian) are good for this type of documentation.
Suggested Structure for Knowledge Base:
- Configuration Section: Document important configurations such as:
  - Network setup (e.g., static IP vs. DHCP)
  - Lightning node configurations (e.g., minimum fee rates, max inbound liquidity)
  - Firewall settings and open ports
- Command Log: Include commonly used commands and any custom scripts.
- Optimization Tips: Keep notes on settings that improve performance or security (e.g., resource limits, rebalancing tips).
- Troubleshooting Section: Document solutions to any recurring issues.

Method 3: Use Git Version Control (Advanced)

If you’re comfortable with Git, version control tools like GitHub, GitLab, or Bitbucket can be used to track changes to configuration files or scripts. This provides version history and allows you to easily revert to previous versions of configuration files.
Example Setup:
- Set up a private Git repository to store your lightningd.conf, bitcoin.conf, and any automation scripts (e.g., rebalancing or monitoring scripts).
- Each time you modify a file, commit it with a clear message describing what was changed.

2. When to Update Your Node’s Documentation

1. After Major Software Upgrades

Whenever you upgrade the Core Lightning software or Bitcoin Core, you should document:
- The version you upgraded from and to.
- Any new features or bug fixes that might affect your setup.
- Special upgrade instructions (e.g., any required database migrations or configuration changes).
- Issues encountered during the upgrade and how they were resolved.

2. After Configuration Changes

Any time you modify the configuration, such as changing the fee structure, adding/removing channels, adjusting network settings, or enabling/disabling services.
Record why the change was made (e.g., “increase fee to 0.01 sat/byte to improve routing success rate”).

3. After Adding or Removing Channels

When you open or close a Lightning channel, document:
- The channel ID, peer information, and amount of liquidity.
- Whether the channel was opened due to liquidity needs, routing opportunities, or for a specific payment.
- Any issues encountered (e.g., high fees, channel closures).

4. After Major Node Troubleshooting

If you troubleshoot a major issue (e.g., node crash, payment failure, channel issues), document the steps you took to resolve the problem.
Example entries:
- Issue: Node disconnected after software update.
- Solution: Restarted the node and checked logs with lightning-cli getinfo to resolve connection issues.

5. When Adding New Features or Services

If you introduce new features or services like monitoring, alerts, or automated scripts, update your documentation to reflect the changes.
Example:
“Implemented automated channel rebalancing script using balance-of-payments.”

3. Steps to Maintain and Update Node Documentation

Step 1: Establish a Standard Format

Set up a standardized format for your documentation, ensuring that all records are clear and consistent.
For example:
- Date: The date the change was made.
- Version/Update: The version of the software or system.
- Change Summary: A brief description of the change.
- Reasoning/Notes: Why the change was made and any important details.

Step 2: Use Timestamps for Tracking

Always add a timestamp or version number for each update so that you can track the progress of the node’s configuration over time.
Example:
“2025-01-24: Updated lightningd.conf to increase minfeepercent for better routing success.”

Step 3: Use Descriptive Commit Messages (if using version control)

For version control systems like Git, commit each configuration change with a clear and descriptive message.
Example:
“git commit -m ‘Updated lightningd.conf to enable new payment routing strategy.’”

Step 4: Store Backups of Key Documentation

Back up your documentation in case of hardware failures. Consider using cloud storage (e.g., Google Drive, Dropbox, or encrypted cloud storage) to ensure that your docs are safe and accessible from anywhere.

Step 5: Review and Refactor Regularly

Revisit and clean up your documentation at least once a month. This ensures that everything is up-to-date and relevant.
Example: Remove outdated notes or configuration settings that no longer apply to your current setup.

Example of a Changelog

Here’s a template for a simple changelog that you can use to document changes to your Core Lightning node:

# Core Lightning Changelog

## [2025-01-24] - v0.11.1 Release

### Added
- Implemented new Lightning payment routing strategy to optimize fees.
- Integrated automated channel rebalancing with `balance-of-payments`.

### Changed
- Increased `minfeepercent` setting to 1% for improved routing success.
- Switched to `Tor` for anonymous routing.

### Fixed
- Resolved issue with stalled payments due to high liquidity imbalance in channel `xyz123`.

### Removed
- Removed inactive channels `abc123456`, `def789101`.

---

## [2025-01-10] - v0.11.0 Release

### Added
- Enabled experimental feature for automatic channel rebalancing.
- Added logging for outbound payment failures.

### Changed
- Modified `lightningd.conf` to adjust minimum payment amounts for liquidity efficiency.

### Fixed
- Fixed issue with Node's DNS resolution failing intermittently.

Proper Names of Each Step:

Review Current Documentation
- Proper Name: Initial Documentation Review
Determine if Documentation is Outdated or Incomplete
- Proper Name: Documentation Status Assessment
If yes (documentation is outdated or incomplete):
1. Gather Information from the Codebase
  - Proper Name: Codebase Information Gathering
2. Identify Missing or Incorrect Details
  - Proper Name: Documentation Gap Identification
3. Write Necessary Updates
  - Proper Name: Documentation Update Writing
4. Review and Test Updates
  - Proper Name: Documentation Review and Testing
5. Final Review and Approvals
  - Proper Name: Final Documentation Review and Approval
6. Publish the Updated Docs
  - Proper Name: Documentation Publishing

If no (documentation is up to date): 3. End (Documentation is up to date)

Proper Name: Process Termination

This GoAT diagram shows a clear step-by-step breakdown of the process for updating node documentation using proper names in each step.

Closing Considerations

Updating your documentation is a fundamental practice to maintain a well-organized and resilient Core Lightning node. This allows you to quickly reference changes, track node performance, and have a reliable history of configurations and troubleshooting steps. Proper documentation aids in efficient maintenance, security audits, and even collaborative work if you’re running the node in a shared environment.