Dancer2 Documentation Grant Report
Fri, 08-Nov-2024 by
Saif Ahmed
edit post
< aka [CROMEDOME](https://metacpan.org/author/CROMEDOME) has submitted a midway report of his [Dancer 2 Documentation](https://news.perlfoundation.org/post/crome_dancer2) project. While the project is undoubtedly an important piece of work, his report is also a perfect example of how grants (or indeed any project) should be done. There is a professional demonstration of discipline, identifying goals, challenges, and successes. He has submitted multiple reports through the term, each of which are transparent and reassuring, and I have posted these below.
<hr>
### First Meeting:
1. Goals and Audience Alignment
We started by aligning the grant goals with the proposal, ensuring a clear understanding of the target audience. My primary aim is to improve the documentation quality, making it more accessible and comprehensive for both new and experienced Dancer2 users.
2. Documentation Review
I reviewed the current documentation to identify areas needing updates and improvements. This step helps me focus on specific issues rather than just broad goals. Key areas of focus include:
- Clarifying core concepts
- Enhancing examples and tutorials
- Updating deprecated methods and practices
- Improving the structure for better readability
We've aligned on these key areas of focus.
3. Approach and Strategy
We discussed the approach for tackling the documentation updates. Specific details include:
- Using story-driven analogies to explain concepts
- Implementing task-oriented sections for better usability
- Ensuring that explanations cater to different levels of user expertise
I will research these ideas to decide what tone and style the documentation will reflect.
4. Critical Details and Use-Cases
We compiled a list of details and specific use cases to cover in the new documentation. These include:
- Simple "Hello, World!" applications
- Detailed route handling examples
- Advanced features like sessions and error handling
- Real-world scenarios and best practices
5. Meeting Schedule and Reporting
We established a regular meeting schedule to ensure consistent progress tracking. Meetings will be held as follows:
- Syncing meetings: Once a month with a weekly hold and room for ad-hoc meetings and updates over email
- Progress reports: First week of every month
This schedule will help us maintain momentum and address any issues promptly.
6. Immediate Next Steps
We outlined the immediate next steps for the documentation work:
- Determine the tone and style of the documentation
- Draft introduction and installation sections using the chosen tone and style
### Dancer2 Documentation Grant Report for July, 2024
_ Stated Goals_
The goal for month 1 was to work on the core of the Dancer2 documentation, `Dancer2::Manual`.
_Work Accomplished_
I spent some time up front talking with my grant manager (Sawyer X) working out a plan of attack and revisiting the planned schedule for the grant. Some things needed to be decided up front: what's the tone of
this going to be? How best do we communicate information to users of Dancer2? How do we organize the mess of information that is the current manual in a more coherent way?
A printed manual has multiple chapters/sections to it; larger manuals may span several volumes. I moved any current documentation that clearly is part of the manual to the `Dancer2::Manual::` namespace. I then gave
each section a clearer purpose (abstract) so someone looking at Dancer2 on MetaCPAN has a better idea of what's in each document. I also revised the documentation map in `Dancer2.pm` to make clearer what is in each section of the manual.
For a theme, I decided to take a friendly and somewhat humorous approach, which matches the demeanor of most of the Dancer Core Team.
The order of sections in `Dancer2::Manual` is being reorganized so concepts presented in the manual build on those previously introduced. Each section explains a new concept and what it is used for, shows a commented example of that concept, then explains the why behind that example - why is it necessary, and why is it done that way.
Core concepts in Dancer2 have been explained in the new manual, and a rewritten approach to routes and route handlers is mostly complete.
_Up Next_
Continued work on the core of the manual. With the first section close to completion, a jump on other sections, and the new format for the layout close to completion, I should be able to focus on producing content for the month of August.
### Dancer2 Documentation Grant Report for August 2024
_Stated Goals_
The goal for month 2 was to work on the core of the Dancer2 documentation, `Dancer2::Manual`.
_Work Accomplished_
The reorganization of content in the manual itself (along with the deployment guide) is complete. Work on content continued into templates and sessions, and some advanced content at the end of the manual has been completed.
I worked with my grant manager, Sawyer, to come up with a set of benchmarks to help us determine what done looks like. This will help me to better identify where effort is still needed, and when I can stop working on other sections.
I’m about 2-2.5 weeks behind where I wanted to be at this point. In the grant application, I asked for half a payment at the halfway point, and the remainder upon completion. I feel I need to complete the month 2 goals in their entirety before I should ask, so we will revisit this topic in the September report (I’ll send in early October).
_Up Next_
Immediate goals consist of catching up on where I want to be in the core manual. After that, I plan to tackle the Deployment Guide and other anscilary documentation.
### Dancer2 Documentation Grant Report for October 2024
_Stated Goals_
Month 3: Example application; review and edit Dancer2::Manual
Month 4: Update and revise the cookbook, deployment, and migration guides; final edits
_Work Accomplished_
Unexpected personal commitments and a recent hurricane impacting my area have led to delays, and the work is now approximately two months behind schedule. Despite these challenges, I have made solid progress and am actively resolving each area as I move forward.
The Manual is essentially complete, pending final reviews before it can be considered finished. Additionally, a new section, Dancer2::Manual::Extending, has been added. This guide covers extension topics, a logical addition that emerged as I wrapped up work on the core manual. The benefit is added readability for users and not having an overwhelming Manual. It is also complete but pending review before it's considered finished.
The cookbook is currently under review, and work is ongoing to define the structure and content of the tutorial. Dancer has a history of difficulties with the Tutorial and we decided to scope it well before I begin the work on it, to maintain clarity for users and focus for my work.
_Up Next_
After reviewing the remaining work with Sawyer last week, we’ve made adjustments to the schedule. The tutorial, which we expect to be a substantial piece, will be completed at the end to ensure it receives the appropriate focus. We’ve prioritized other items to facilitate timely completion of all areas. The remaining tasks are as follows:
* Finalize the Cookbook (expected to complete quickly)
* Review and revise the Deployment Guide
* Review and revise the Keyword Guide (expected to complete quickly)
* Publish the above for public review
* Write the tutorial
* Process feedback from public review and incorporate relevant changes
You can follow ongoing progress at https://github.com/PerlDancer/Dancer2/tree/docs/doc-rewrite-grant
]]>
Comments (0)
