The task is to improve the user-facing and developer-facing documentation for the Xeus-clang project
Owing to the nature of the project, the entire documentation can be split into two (or more) user profiles. To make the documentation more accessible and user-friendly, it could be helpful to create user profiles, two of which are most common would be 1. Users( I am a User ) 2. Developers( I am a Developer) These profiles would make it easier for people to find their use-case for Xeus-clang as well as for the maintainers as they can tailor the documentation to their specific needs and interests.
(Since Xeus-clang-repl would also be heavily used by scientists and researchers, another user profile for them can be added and certain documentation pertaining to them can be added too )
There would be some sections which would be common to both the users as wells as the developers. However the user-facing documentation would be more focused on the basics as well as the hands-on tutorials in order for the users to quickly get started with using the extension
(For simplicity, I have made a rough flowchart of how the documentation would be structured. Its a rough estimate and several sections might be added or subtracted according to needs)
%% Flowchart
graph TD;
A[Documentation] -. User Profile .-> D{What are you?}
D -->B(I am a user)
D --> C(I am a Developer)
B --> E[(User Specific Docs)]
subgraph User
E[(User Specific Docs)] --> F{{Getting started}}
F{{Getting started}} --- H{{User Guide}}
H{{User Guide}} --- I{{Common Code Cases}}
I{{Common Code Cases}} --- K{{Troubleshooting and FAQs}}
end
subgraph Developer
C(I am a Developer) --> G[(Developer Specific Docs)]
G[(Developer Specific Docs)] --- L{{Installation and Setup}}
L{{Installation and Setup}} --- M{{Developer Guide}}
M{{Developer Guide}} --- N{{API Reference}}
N{{API Reference}} --- K
end
subgraph Independent
V([Cross References]) --- W([Glossary])
W --- X([User Feedback and Support])
X --- Y([Where are we using it ?])
Y --- Z([Contribute])
end
More information regarding the breakdown
-
Getting started - This would typically include information that helps a user get up and running with the tool quickly. Some of the things that are typically included but is not limited to are :
- Installation Instructions
- Configuration Instructions
- Sample Data or templates
- Troubleshooting tips
-
User Guide - This section could include information on how to use Xeus-Clang-REPL to accomplish common tasks or workflows. It could provide step-by-step instructions, screenshots, and examples to help users understand how to use the tool effectively
-
Common Code Cases - Common use cases for users and their corresponding codes would be available in the form of 'Code Examples' Instead of just listing features and providing usage instructions, the documentation could include interactive examples that allow users to see Xeus-Clang-REPL in action. This could include providing interactive code snippets or notebooks to users, or embedding interactive widgets directly into the documentation. The documentation could also include tutorials or walkthroughs that guide users through common use cases and workflows. This could entail creating step-by-step instructions for using Xeus-Clang-REPL for specific tasks or projects.
-
Installation and Setup - This section could include information on how to install and set up Xeus-Clang-REPL for development purposes. It could include instructions on how to build the tool from source code, or how to integrate it with other development tools or environments.
-
Developer Guide: This section could include information on how to use Xeus-Clang-REPL for development purposes, such as how to create custom plugins or extensions. It could provide detailed technical information and examples for advanced users.
-
API Reference: This section could include a detailed reference guide for the Xeus-Clang-REPL API, providing information on all the available functions, classes, and methods. It could also include code examples and usage tips to help developers use the API effectively.
-
Troubleshooting and FAQs: This section could include troubleshooting guides and frequently asked questions that address common issues or questions that users or developers both may have.
There would be some of the sections which would be independent of the user personas i.e they would be helpful for all those who wish to use Xeus-Clang-REPL or contribute to it. Some of them maybe
- Cross References - links within documentation that allow the user to navigate to related information within the same document or to external resources. This may include links related to documents or manuals, code samples, or to external resources such as online forums, help sites, research papers etc.
- Glossary - Provides definitions for key terms and technical jargon used throughout the document for easy reference.
- Where are we using it ? - Documentation can be made more relatable by providing real-world examples of how Xeus-Clang-REPL is being used in industry or research. These examples can help developers understand how the tool can be applied to different use cases and help inspire them to explore new possibilities.
- Contribute - To encourage the visitors to be a part of the community by actively contributing to the code as well as the documentation.
- Version Control - Git
- Markdown languages - Markdown/Restructured Text
- Documentation tools - Sphinx
Why Sphinx ? Built-in support for Python, Easy integration with version control systems such as git and svn, Customizable themes and also support for reStructuredText markup.
- Code Embedding - Binder
Why Binder ? For running interactive code examples, Binder which is a platform for creating and sharing interactive computing environments that allow users to run and modify code in the cloud be ideal. Binder creates a Docker container with the necessary environment and launches a Jupyter Notebook or JupyterLab session. Users can then interact with the code examples directly in their web browser, making changes and running the code in real-time.real time