Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: restructure the main navigation and reposition some sections. #383

Open
4 tasks
stickgrinder opened this issue Jan 16, 2025 · 0 comments · May be fixed by #384
Open
4 tasks

Documentation: restructure the main navigation and reposition some sections. #383

stickgrinder opened this issue Jan 16, 2025 · 0 comments · May be fixed by #384
Assignees
Labels
documentation Improvements or additions to documentation improvement New feature or request

Comments

@stickgrinder
Copy link
Collaborator

Benefit description

We stubbed a structure of the documentation before 2.0 release, and it made sense on paper.

At this point thou, some sections outgrewed their initial scopes (mainly, the "Create a game stub" section, who became so large it can actually be considered as the content of the "How to develop a game" section, maybe with some additions?

So, we are going to reorganize the navigation, removing redundancy and making the most out of what we already have, so we can focus on the missing parts.

Solution description

  • Settle on one among How to develop a game and Getting Started > Creating a game stub. Maybe we need both but the content must be reorganized somehow! (note: maybe we can change "Creating a game stub" with "Get your hands dirty" and write a small guide based on the sample game, showcasing the very basics of Popochiu)
  • Add and "Advanced techniques" or "Guides and how-tos" section for advanced or more vertical stuff
  • Add an "Understanding Popochiu" section for some explanations (not tutorials) that help people getting a grasp of the logic behind all of the Engine's elements (use the Contribution section as a guideline!)
  • The contribution guide has a table on the sections of the docs, and the reference to diataxis framework for their content. Make sure it's updated to reflect the new docs structure!

The new section should look more or less like this:

- Getting started
  - Installing popochiu
  - Get your hands dirty
  - Example resources
  - Tutorials
  - Getting help

- How to develop a game
  - < ... current content of the "Creating a game stub" section ... >

- How-tos and Tutorials
  - <  ... Current content of the  "How to develop a game > Advanced Techniques" section ... >

- The editor handbook
- The engine handbook
- Contribution guide

Exclusions

We are not going to write missing parts now, we are just going to move what we have to make it more intuitive to find information.

Small adjustments may be necessary (linking, phrasing, etc), but keep the scope small so we can release asap.

Implications

Some link that are outside the docs (old messages, project pages, etc) will be moved. This can break the experience for some users. That's a good moment to investigate if we can create a redirection map so the docs will always appear consistent over time.

@stickgrinder stickgrinder moved this to Backlog in Popochiu Jan 16, 2025
@stickgrinder stickgrinder moved this from Backlog to Ready in Popochiu Jan 16, 2025
@stickgrinder stickgrinder self-assigned this Jan 16, 2025
@stickgrinder stickgrinder added documentation Improvements or additions to documentation improvement New feature or request labels Jan 16, 2025
@stickgrinder stickgrinder linked a pull request Jan 16, 2025 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation improvement New feature or request
Projects
Status: Ready
Development

Successfully merging a pull request may close this issue.

1 participant