SysIdentPy Documentation Restructuring Proposal¶

This document outlines a reorganization of SysIdentPy’s documentation to improve discoverability, reduce friction for beginners, and align with modern documentation standards. The structure will follow four key categories: Tutorials, How-Tos, Explanations, and Reference Guide, with additional sections for contributors and real-world examples.

Acknowledgments: This documentation restructuring draws inspiration from NumPy’s NEP 44, adapting its principles of clarity and logical organization to SysIdentPy’s domain-specific needs in system identification and time series forecasting, while emphasizing tutorials and reproducibility.

Motivation and Scope¶

SysIdentPy’s current documentation (like many scientific Python packages) mixes conceptual explanations, code examples, and API references, which can overwhelm new users. By adopting a user-centric structure inspired by Diátaxis, we aim to:

• Separate learning paths for beginners (Tutorials) and practitioners (How-Tos).
• Improve material for conceptual understanding (Explanations).
• Maintain a clean, searchable Reference Guide.
• Highlight SysIdentPy’s features.

A well-organized documentation structure can significantly improve the experience of our community by providing specific resources for different user groups:

• For Beginners: A clear, guided pathway with tutorials and step-by-step instructions helps new users overcome the learning curve.

• For Researchers: Features such as custom basis functions and model configurations can be easily discovered and understood. With clearly defined sections, researchers can quickly locate the information they need to experiment with new methods.

• For Industry/Corporate Users: Benchmarking guides and model comparison examples are readily accessible, making it easier for industry and corporate professionals to evaluate and choose the right tools for their specific needs.

The goal is to structure the documentation to meet the specific needs of these diverse user groups, making the learning process faster and more efficient for everyone in the community.

Proposed Structure¶

Here’s an overview of the main sections in the documentation, outlining the purpose and proposed content for each:

• Getting Started
• User Guide
• Developer Guide
• Community & Support
• About

User Guide¶

The User Guide section is designed to provide a comprehensive understanding of SysIdentPy, covering essential concepts, practical examples, and advanced features. The proposed structure includes:

Tutorials¶

Audience: New users with minimal system identification experience.

Suggested Content:

Format: Jupyter Notebooks with narrative explanations and code.

How-Tos¶

Audience: Practitioners solving specific problems.

Suggested Content:

Format: Short, task-focused markdown files with code snippets.

Explanations¶

Audience: Users seeking rigorous mathematical foundations.

Reference Guide¶

Audience: Advanced users needing API details.

Format: Auto-generated API docs with cross-linked "See Also" sections.

Developer Guide¶

The Developer Guide section aims to provide clear information on the internal structure of SysIdentPy, focusing on implementation details, code examples, and options for customization. The proposed structure includes:

How To Contribute¶

Audience: Maintainers and open-source contributors.

Documentation Guide¶

Audience: Maintainers and open-source contributors.

Community & Support¶

Audience: Individuals of all experience levels, from beginners to experts, with an interest in Python and SysIdentPy.