Docs homepage enhancement #5161
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,58 +1,72 @@ | ||
| <div class="img-responsive"> | ||
| <img src="/images/terasology-logo.png" alt="Terasology Banner" width="300"> | ||
| </div> | ||
|
|
||
|
|
||
| # Welcome to Terasology! | ||
|
|
||
| 🌟 **Embark on an open-source adventure** where you can contribute, play, and explore the world of Terasology. | ||
|
|
||
|
|
||
| Whether you're here to join the community, contribute to the project, or just learn more about the game, we've got you covered. | ||
|
There was a problem hiding this comment.
This comes across as very marketing-oriented language. We're not trying to sell the game here, just document how the game works and how to develop for it. Saying things like "we've got you covered" tends to make me feel defensive, since I have no personal connection with the "voice" of the documentation. Try to focus more on the content, rather than the reader. A bit of enthusiasm is fine though. There was a problem hiding this comment. thanks for directing me to the actual developer documentation, my focus was on the wiki documentation. Your suggestion here is noted. There was a problem hiding this comment. any suggestion on how to restructure it is welcome. There was a problem hiding this comment. I agree that it sounds a bit too "flashy" for our typical audience. Sounds a bit like it was generated with ChatGPT, but the prompt lacked some directives for more technical language... There was a problem hiding this comment. Regarding the words, "Whether you're here to join the community, contribute to the project, or just learn more about the game, we've got you covered." I remove and use the previous words instead. "This wiki does not cover game content or how to play the game in much detail, but you can find more information on these topics here" |
||
|
|
||
| ## Understanding Terasology | ||
|
|
||
| Terasology is a mosaic of many components, beautifully combined to create a sandbox for your imagination. | ||
|
There was a problem hiding this comment. I wish that was true... Let's tone it down a bit though. How about something like this?
There was a problem hiding this comment. Should modules be a hyperlink? The module link you provided is differents from what I have in the wiki. |
||
|
|
||
| - 🏛️ **[Architecture Overview](Codebase-Structure.md)** | ||
| - Understand the high-level structure of the project. | ||
| - 🔧 **[Entity System Architecture](Entity-System-Architecture.md)** | ||
| - Dive into how our entity system powers the game. | ||
| - 🎲 **[Events and Systems](Events-and-Systems.md)** | ||
| - Explore how to inject new logic and life into the game. | ||
| - 🏗️ **[Block Architecture](https://github.com/Terasology/TutorialAssetSystem/wiki/Block-Attributes)** | ||
| - Delve into the building blocks of the game world. | ||
|
|
||
|  | ||
|
There was a problem hiding this comment. This image alone looks a bit out of place with the new page content. It might be better off being moved to the codebase structure page now. |
||
|
|
||
|
|
||
| ## Quick Links | ||
|
|
||
| - **[🎮 Start Playing](https://github.com/MovingBlocks/Terasology/blob/develop/docs/Playing.md)** | ||
|
There was a problem hiding this comment. That page was temporarily moved to https://github.com/MovingBlocks/Terasology/blob/develop/docs-pre-merge/Playing.md. Long-term, it should probably be moved into the documentation site as well. |
||
| - **[🏗️ Developer's Hub](Contributor-Quick-Start.md)** | ||
| - **[🛠️ Troubleshooting](Troubleshooting.md)** | ||
| - **[🛠️ Maintainer's Dashboard](Maintenance.md)** | ||
|
|
||
| ## Community and Support | ||
|
|
||
|
There was a problem hiding this comment. The information removed here is somewhat important. Are you planning to reintroduce it somewhere else? There was a problem hiding this comment. i we add it back to the home page and figured out the right positioning for it |
||
| Join the discussions, seek support, and contribute to the community. | ||
|
|
||
| - 👋 [Discord Server](https://discord.gg/terasology) - For live discussions and support. | ||
| - 📚 [Forum](https://forum.terasology.org/forum/) - For project updates and inspiration. | ||
|
There was a problem hiding this comment. Unfortunately, the forum is mostly abandoned. It stays up for the historical posts but there is next to no new activity on there anymore. It might be more appropriate to stop promoting it for now (although we can still mention it as a source of historical interest). There was a problem hiding this comment. Thanks for pointing this out, I we come up with an idea on this. |
||
|
|
||
| ### Getting Help | ||
|
|
||
| - For gameplay questions: Use the `#play-terasology` channel on Discord. | ||
|
There was a problem hiding this comment. If players believe that they've found a bug then we'd normally recommend they create an issue on GitHub as well. Discord tends to be more for discussions and general support. There was a problem hiding this comment. If discord is for discussion and general support, that means we can update it with the actual discord details. |
||
| - For development support: Post in the `#terasology` channel or [open an issue on GitHub](https://github.com/MovingBlocks/Terasology/issues/new/choose). | ||
|
|
||
| ## Getting Started as a Contributor | ||
|
|
||
| 🚀 Ready to dive into development? Check out the [Contributor Quick Start](Contributor-Quick-Start.md) guide to set up your workspace, understand the required tools, and make your first contribution. | ||
|
|
||
| - Get familiar with [Git and GitHub basics](https://docs.github.com/en/get-started/quickstart/hello-world) for collaborating on code. | ||
| - Set up your Terasology Development Workspace and start playing around with the code. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| Encountering issues? Our [Troubleshooting guide](Troubleshooting.md) offers solutions for common problems faced by players and developers alike. | ||
|
|
||
| - Find quick fixes and helpful resources for common issues. | ||
| - Get additional support by reaching out on [Discord](http://discord.gg/Terasology) or our [Support Forum](http://forum.terasology.org/forum/support.20). | ||
|
|
||
| ## Stay Updated & Reach Out | ||
lokytech5 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 📢 We love sharing updates and hearing from you! | ||
|
|
||
| - **[Discord](https://discordapp.com/invite/terasology)** - For `#announcements` and direct Q&A. | ||
| - **[GitHub (Engine)](https://github.com/MovingBlocks/Terasology)** - Watch the engine or modules for real-time updates. | ||
| - **[GitHub (Modules)](https://github.com/Terasology)** - Watch the module repos for game content fixes / changes. | ||
| - **[Forum](http://forum.terasology.org/)** - Find the progress reports of ongoing and past GSoC projects | ||
| - **[Twitter](http://twitter.com/#!/Terasology)** - Follow for tweet-sized news. | ||
| - **[Facebook](http://www.facebook.com/pages/Terasology/248329655219905)** - Like us for updates in your feed. | ||
| - **[Jenkins RSS](http://jenkins.terasology.org/rssAll)** - For the keen observers of new builds. | ||
|
There was a problem hiding this comment.
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| <div style="text-align: center; margin-top: 2em;"> | ||
| <img src="/images/terasology-logo.png" width="300" alt="Terasology Logo"> | ||
| </div> | ||
|
|
||
| <h1 style="text-align: center;">Terasology Wiki <small>updated</small></h1> | ||
|
There was a problem hiding this comment. The There was a problem hiding this comment. I am unsure about the benefit of having a cover page here at all. Having to scroll down to actually see the documentation has confused me on several occasions. |
||
|
|
||
| <p style="text-align: center;"> | ||
| Dive into the open-source world of Terasology and discover an expansive universe created by a vibrant community. | ||
| </p> | ||
|
|
||
| [GitHub](https://github.com/MovingBlocks/Terasology) | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,59 +1,70 @@ | ||
| <!DOCTYPE html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="UTF-8" /> | ||
| <title>Terasology - Knowledge Base</title> | ||
| <link rel="stylesheet" href="styles.css" /> | ||
| <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> | ||
| <meta | ||
| name="google-site-verification" | ||
| content="AEyBzDSx59v83eaRwdY3ghuYBa4g072fzgMdtQiCCn8" | ||
|
Comment on lines
+8
to
+10
There was a problem hiding this comment. I know that this predates your changes but does anyone recall what this is for? There was a problem hiding this comment. I have no idea about what it is, but when I just checked, this is what it means [The "google-site-verification" meta tag is used to confirm that you have access to the website's backend and can make changes to its code.] |
||
| /> | ||
| <meta | ||
| name="description" | ||
| content="An open source voxel game - imagine the possibilities!" | ||
| /> | ||
| <meta | ||
| name="viewport" | ||
| content="width=device-width, initial-scale=1.0, minimum-scale=1.0" | ||
| /> | ||
| <link | ||
| rel="stylesheet" | ||
| href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" | ||
| /> | ||
| </head> | ||
|
|
||
| <body> | ||
| <div id="app"></div> | ||
| <script src="//cdn.jsdelivr.net/npm/docsify-edit-on-github"></script> | ||
| <script> | ||
| window.$docsify = { | ||
| name: "Terasology", | ||
| repo: "MovingBlocks/Terasology", | ||
| logo: "/images/terasology-logo.png", | ||
|
There was a problem hiding this comment. The icon in the sidebar appears a bit too tall, in my opinion. It displaces the start of the content almost a third of the way down the page. There was a problem hiding this comment. the sidebar icon can be reduced to any size. just let me know the actual width and height. There was a problem hiding this comment. I wouldn't go with fix width and height but with a percentage if possible. |
||
| themeColor: "#08A045", | ||
| loadSidebar: true, | ||
| coverpage: true, | ||
| autoHeader: true, | ||
| search: "auto", | ||
| //homepage: 'https://raw.githubusercontent.com/MovingBlocks/Terasology/develop/README.md', | ||
| homepage: "Home.md", | ||
| pagination: { | ||
| crossChapter: true, | ||
| crossChapterText: true, | ||
| }, | ||
| plugins: [ | ||
| EditOnGithubPlugin.create( | ||
| "https://github.com/MovingBlocks/Terasology/tree/develop/docs/" | ||
| ), | ||
| // function (hook) { | ||
| // // this "fixes" the relative links in the README which is loaded from remote (see 'homepage' above) | ||
| // hook.beforeEach(function (content) { | ||
| // return content | ||
| // .replace(new RegExp("https://raw.githubusercontent.com/MovingBlocks/Terasology/develop/docs/"), "") | ||
| // .replace(new RegExp("./docs/"), ""); | ||
| // }) | ||
| // } | ||
| ], | ||
| }; | ||
| </script> | ||
| <!-- Docsify v4 --> | ||
| <script src="//cdn.jsdelivr.net/npm/docsify@4"></script> | ||
| <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script> | ||
| <script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script> | ||
| <script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script> | ||
|
|
||
| <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script> | ||
| <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json5.min.js"></script> | ||
| <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script> | ||
| </body> | ||
| </html> | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| .img-responsive { | ||
| text-align: center; | ||
| display: flex; | ||
| justify-content: center; | ||
| align-items: center; | ||
| height: 100%; | ||
| } | ||
|
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel like this "home" page should be the split-off point to the "hubs" for the different audiences (players, devs, maintainers), similar to how we did it in http://terasology.org/Terasology/#/Troubleshooting
Also, I feel like this page is very very long - ideally I would imagine it as the jump-off point into the dedicated hubs + some references to the most important links to get additional help (community/support), which btw I think are duplicated in "Community and Support", "Getting Help", "Troubleshooting", and "Stay Updated & Reach Out"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You are right about making the homepage split-off point to the "hubs" for different audiences. What about the quick links section? It can cover different audience, and regarding the duplicates, we can have "Getting Help and Support," which refer to opening an issue in GitHub, and "Troubleshooting," which refer to the troubleshooting guide. The Announcement Channels remain the same.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we can keep some quick links on the "home" page, yes, but we should consider what would be relevant for all audiences to get direct access to. I think troubleshooting, opening an issue, and maybe a link to our discord server might be reasonable candidates. any further ideas?