Replies: 2 comments 1 reply
-
|
Very interested in seeing this come to fruition |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
Hi, |
Beta Was this translation helpful? Give feedback.
1 reply
-
|
@white-hawk-73 thanks for your interest in the proposal. Sadly, it was not accepted and thus we won't be moving forward with it. |
Beta Was this translation helpful? Give feedback.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Stipple.jl documentation overhaul
Genie Framework is a powerful web application framework for the creation of full-stack apps in Julia. It is formed by three main compoments: Genie.jl, the server, Stipple.jl, the reactive UI generator, and SearchLight.jl, the ORM. Despite its innovative design and rich features, the framework's documentation is far from complete, making it difficult for new users and developers to start contributing and utilizing its full potential.
Given the current rise in web UI development frameworks, Stipple is gathering increasing attention from users and developers. Moreover, it is approaching API stability which ensures a consistent and reliable interface for building applications. As a result, the users can expect a more dependable and predictable development experience, encouraging further adoption of the framework. Thus, Stipple is the ideal candidate in the framework for extensive documentation work.
The aim of this project is to create a comprehensive, easy-to-navigate, and informative documentation for Stipple, catering to both beginner and experienced members of the community. This will improve the onboarding process, increase contributions, and ultimately drive the growth of the project.
Project Scope
The scope for the project includes the following aspects:
Evaluate and consolidate existing documentation: identify the current state of Stipple.jl documentation, including gaps and inconsistencies, by thoroughly reviewing available resources.
Develop a well-organized documentation structure: design a logical and user-friendly structure that caters to various skill levels, promoting ease of navigation and efficient information retrieval. One example of such is the documentation for Adonisjs, which is concept-based and covers the features in the framework.
Document features and concepts: provide clear explanations and examples for the features and concepts used in building reactive UIs with stipple, such as data bindings, event handling, or routing.
Provide detailed API reference: document in detail the Stipple API, especially the calls that handle interaction and the ones generating UI components.
Produce comprehensive tutorials: write step-by-step tutorials that demonstrate the features and capabilities of Stipple.
Document advanced use cases: explain more complex scenarios such as the creation of custom UI components, multi-page applications, or resource-intensive UIs.
Maintain and update documentation: establish a process for keeping the Stipple documentation up-to-date with future changes and enhancements in the framework, with the possibility of having multiple versions.
Not in the scope of the project:
How will the writer work with the organization?
To ensure the successful development of Stipple's documentation, the technical writer will work closely with the organization and its members throughout the entire process. The writer's mentor will be Pere Giménez, Developer Advocate at Genie. Moreover, Julia developers from the team will also help the writer understand the code and troubleshoot issues.
The workflow will be git-based, where the API docs will reside on the Stipple GitHub repository, and the remaining documents will be on the documentation website repository.
For each documentation task, the writer or mentor will create a GitHub issue in the doc site repository, outlining the scope, goals, and requirements. Issues will be assigned to milestones corresponding to different stages of the documentation process.
The writer will work on assigned issues, creating new branches in the repository for each task. This will help keep the work organized and prevent conflicts between different tasks.
Once a documentation task is completed, the writer will commit their changes and create a pull request. The mentor or a team member will review the PR, providing feedback and suggestions for improvement.
When the pull request has been approved by the reviewers, it will be merged into the main branch, and the associated issue will be closed.
The writer and mentor will continuously monitor the project for new developments or changes that may require updates to the documentation. New issues will be created and followed through the workflow as needed to keep the documentation up-to-date and accurate.
Throughout the documentation development process, the writer will maintain regular contact with the organization's members, seeking guidance, feedback, and clarification on technical aspects. This engagement will help ensure that the documentation is accurate, comprehensive, and consistent with the project's standards. The writer will also participate in community discussions and follow the project's progress on GitHub, staying informed about updates, issues, and new features that may impact the documentation.
How will we measure success?
The success of this project will be measured in terms of the quantity and quality of the generated documentation, and its impact on the community. Specifically, we will evaluate:
What skills would a technical writer need to work on this project?
Must have:
Nice to have:
Project timeline
The project is expected to take 5-6 months, depending on the writer's experience. There will be an initial orientation period during which the writer will learn about reactive UI development with Stipple, and familiarize themself with the codebase to be documented.
Budget
The budget will be spent on the writer's stipend, a volunteer stipend, and swag or equipment for the writer. The volunteers will be contributors from the community, who will also collaborate with the writer in documenting their contributions.
How to apply
Interested technical writers can directly send an email to [email protected]. Please include your CV and links to writing samples.
Beta Was this translation helpful? Give feedback.
All reactions