Docs homepage enhancement #5161
Conversation
There was a problem hiding this comment.
I've had a look over these changes and have a few suggestions for improvement. If you don't agree with anything I've suggested then you are welcome to say so and explain why.
Just for clarification, this is primarily the developer documentation here. MovingBlocks/movingblocks.github.com (which is terasology.org) contains a more player-facing view.
docs/Home.md
Outdated
|
|
||
| ## Joining the Community & Asking for Help | ||
| 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.
Whether you're here to join the community, contribute to the project, or just learn more about the game, we've got you covered.
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...
This is not so much about the structure as it is about the "tone".
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"
docs/Home.md
Outdated
|
|
||
| Our [forum](https://forum.terasology.org/forum/) is currently mainly used to track progress of our GSoC student projects. | ||
| However, it has a lot of more or less actionable ideas for improvement and a bunch of history of our current gameplays floating around, so feel free to roam around a bit and get inspired :wink: | ||
| 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?
Terasology itself is a pure sandbox. Gameplay is implemented through modules, which can add anything from new blocks and crafting methods to entirely new game modes.
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.
docs/Home.md
Outdated
|
|
||
| All Terasology modules reside in the [Terasology](https://github.com/Terasology) Github organization. | ||
| - 👋 [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.
docs/Home.md
Outdated
|
|
||
| These pages offer more advanced insight into how specific features of the game are architected and why. | ||
| - 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.
| <meta | ||
| name="google-site-verification" | ||
| content="AEyBzDSx59v83eaRwdY3ghuYBa4g072fzgMdtQiCCn8" |
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.]
docs/Home.md
Outdated
| - **[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.
jenkins.terasology.org has not been in use for a long time. https://jenkins.terasology.io/rssAll would be the current URL.
docs/Home.md
Outdated
|
|
||
| Interested in getting involved with working on the game? Make sure to check out the [Contributor Quick Start](Contributor-Quick-Start.md) for setting up your first workspace and starting the game from source. It also has useful links on how to start with your first contribution. | ||
|  |
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.
docs/Home.md
Outdated
|
|
||
| Terasology is build from many building bricks, that together turn into a game. | ||
| - **[🎮 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.
|
|
||
| This core is backed by several in-house _libraries_, such as([MovingBlocks/gestalt](https://github.com/MovingBlocks/gestalt)) providing the entity system and module management, or our own UI library ([MovingBlocks/TeraNUI](https://github.com/MovingBlocks/TeraNUI)). |
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
There was a problem hiding this comment.
All in all, this currently feels like you're starting to move things around without having a proper concept / plan in your mind. Consider going back to the drawing board and mapping out the sections you want to create, taking into account how a member of each audience group would be able to easily and quickly find information they need.
Especially for players and potentially developers, being new around here, I would guess that you can think of information that you were interested when you first arrived and are interested now that you're actively contributing.
|
|
||
| It doesn't cover game content or how to play the game much, but check out the docs on [Playing](https://github.com/MovingBlocks/Terasology/blob/develop/docs/Playing.md) (including hotkeys etc) and [Modules](https://github.com/MovingBlocks/Terasology/blob/develop/docs/Modules.md) for some of that. | ||
| # Welcome to Terasology! |
There was a problem hiding this comment.
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.
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.
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?
docs/Home.md
Outdated
|
|
||
| ## Joining the Community & Asking for Help | ||
| 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.
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...
This is not so much about the structure as it is about the "tone".
| <meta | ||
| name="google-site-verification" | ||
| content="AEyBzDSx59v83eaRwdY3ghuYBa4g072fzgMdtQiCCn8" |
| window.$docsify = { | ||
| name: "Terasology", | ||
| repo: "MovingBlocks/Terasology", | ||
| logo: "/images/terasology-logo.png", |
There was a problem hiding this comment.
I wouldn't go with fix width and height but with a percentage if possible.
Also, I think having the icon on top of the navigation is sufficient - it doesn't need to be on the "home" page as well
regarding this, there is a plan and idea in mind; if not, I wouldn't have given the idea structure at the beginning. what's mainly confusing me is how the different links within a particular md file link to different sections, and when I tend to keep track, i get lost. |
|
@jdrueckert Regarding the developer hub link on the homepage, the link points to [Contributor Quickstart Guide]. Is it okay to leave it as it is, or not? |
The contributor quick start guide is mainly relevant for first time contributors or contributors that come back after some time and need to get their workspace updated. so it's an important resource at very specific (few and short) times in your contributor / developer experience, but all other times you don't need it, so I think it should rather be a link rather than the developer hub. |
|
Hello, I am having an issue trying to push my current changes made. should I update the branch with merge commit? |
That's probably because I updated your branch's upstream with develop here on GitHub. |
…ch5/Terasology into docs-homepage-enhancement This merge is to update my existing branch which was behind the remote changes.
|
@jdrueckert i just push the required changes for the homepage required by @BenjaminAmos |
|
Hi @lokytech5 The "home" page for my taste still holds too much information while the branch-off points to the respective audience's "main hub" are not noticeable enough. I want people to directly see where they need to go without having to scroll or search the site much. As the "home" page is mainly the "jump-off" point, it can be very simple and minimal, like so (not very pretty but you get the gist): We can always add more if we feel like (or get feedback that) something's missing. For the two hubs for players and developers, it would be great if you could come up with a list of information you think these groups would look for most often or with most priority - that should be the resources that should be easily accessible via the hub. If you already have an idea of how you want to design the hubs, a rough sketch / outline / mockup would be great 😊 |
|
oh, I get the full gist. I we let you know when I come up with a mockup |
|
Good day, @jdrueckert, I hope you are well. Here is the mock-up data I came up with for players and developers; regarding the icons used, I just picked the ones I feel are okay for a better description. your suggestion on any of them is highly welcomed. |
|
i await your feedback on that |
|
@lokytech5 can you split out parts which are not discussed, and leave others for later? |
|
@lokytech5 thank you for the proposals and sorry for the long feedback time, with being sick and public holidays, the last weeks went by too fast. generally I'd prefer a horizontal design over a vertical one as by default most people use monitors with a landscape ratio. phones would be different, but I think neither players nor developers would browse Terasology documentation by default on their phones. for both hubs, I'm not a big fan of the texts. I don't have a good alternative at this moment in time, though, guess that's something better done once the rest is complete. for the player landing page:
for the developer landing page:
|
jdrueckert
added
the
Status: Needs Author Input
|
hello @jdrueckert, sorry for my late reply, hope you are better and ok regarding your health. about horizontal design rather than vertical design, the horizontal design we be much better for mobile and about the icons, fontawesome can indeed be use, but my main aim was to show you the design i came up with. regarding the name "Players" vs "Developer Hub", can we create a pool to inform developer and players which did they prefer rather than we decide on which to use. regarding the player homepage, you said you are missing troubleshooting, do you mean a link with list of issue solve or yet to solve on the homepage. regarding the FAQs, if is not there yet, it can be removed. you said "a link to module search we be better in the homepage", is module more relevant to players or developers. such facts need to be consider. regarding the installation guides, since is more about world and server setup, then a link to the Terasology launcher docs we be more better. for the developers hub homepage, the code sample i added is to give developers a hint of the type of language use to develop Terasology. for the comminty support session is for developer having issues with any of terasology modules, setting it up, working with it while developing e.t.c. for the tutorial part, is indeed better to add it. as for this "can you elaborate a bit on how you plan to organize all the content we have in our docs into the 4 sections you have so far? |
No worries and yes, I am better, thank you 🙂
True, but I'm questioning whether the majority would actually access our knowledge base from their phone ... Terasology is a game that cannot be played on your phone, you need a computer for that - so it's IMO more likely that people access our docs on their computers, not their phones. Our website is a different story of course, but that's not the target here.
Noted. Still, if we want to merge this PR at some point, we want to strive for a consistent style. We already use fontawesome icons in various places, so we should stick to that.
Theoretically, I really like that approach. However, considering that our active community is currently very small, I'm not entirely sure it's worth the effort at this point in time.
I mean a link to the already existing troubleshooting resource we have (see https://terasology.org/Terasology/#/Troubleshooting and subsequent links)
There are bits and pieces strewn about that could be considered answers to frequent questions, but I'm not aware that we have FAQs in the sense of a list of dedicated questions and respective answers.
Modules are equally relevant to players and (module) developers. For players the interesting part about a module is the features it adds to the gameplay if activated so a player can understand the impact it will have on their gameplay and decide whether they want to enable it or not. For (module) developers, the interesting part is the module API, especially events that a system in a different module might listen and react to.
While the Terasology Launcher is the main installation path for Terasology it is not the only one, so yes, the launcher docs should definitely be linked, but no, it shouldn't be the only reference here. Alternative installation paths in case somebody faces issues with the launcher as well as installation guidance for headless servers are relevant resources for (advanced) players.
I'm not entirely sure how much value a code sample would bring here. While I can imagine something representative of the ECS approach, I think it's hard to find a suitable code sample that would represents the entirety of our code base and thus be suitable for the top page of the developer hub. And for ECS there already is a dedicated tutorial module with lots of code samples.
for that I think a "Help & Support" section with a list of direct links to open a GitHub issue or joining our Discord is an easier approach as it provides faster access to those places where support can be requested.
I understand and agree with the approach. It would be great if you would provide a rough sketch of that tree-style structure with the actual content we currently have 👍
I'm working on that, thank you 💚 and welcome to the new year to you too! |
Contains