search

MovingBlocks / Terasology

Terasology - open source voxel world
http://terasology.org
Apache License 2.0
3.64k stars 1.33k forks source link

Docs homepage enhancement #5161

Open lokytech5 opened 7 months ago

lokytech5 commented 7 months ago

Contains

lokytech5 commented 7 months ago

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.

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.

lokytech5 commented 7 months ago

@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?

jdrueckert commented 7 months ago

@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.

lokytech5 commented 7 months ago

Hello, I am having an issue trying to push my current changes made. should I update the branch with merge commit?

jdrueckert commented 7 months ago

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. You'll need to pull the latest changes from the upstream (git pull).

lokytech5 commented 7 months ago

@jdrueckert i just push the required changes for the homepage required by @BenjaminAmos

jdrueckert commented 7 months ago

Hi @lokytech5 the introductory text sounds way better now IMO :+1:

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): image

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. For maintainers I can help as I don't expect you to be familiar with the docs a maintainer typically needs :slightly_smiling_face:

If you already have an idea of how you want to design the hubs, a rough sketch / outline / mockup would be great :blush:

lokytech5 commented 7 months ago

oh, I get the full gist. I we let you know when I come up with a mockup

lokytech5 commented 6 months ago

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. mock1 (2) mock1 (3)

lokytech5 commented 6 months ago

i await your feedback on that

soloturn commented 6 months ago

@lokytech5 can you split out parts which are not discussed, and leave others for later?

jdrueckert commented 6 months ago

@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. also in general, if you are looking for icons, please use FontAwesome to keep it consistent with other icons we use.

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. also please be consistent with naming, e.g. "Players" vs "Developer Hub" -> should be either "Players" and "Developers" or "Player Hub" and "Developer Hub".

for the player landing page:

for the developer landing page:

lokytech5 commented 5 months ago

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? consider building up a tree-style structure indicating which docs can be accessed via which paths (basically how a doc reader would click through the different levels) and take care that the paths don't get to long and that there should be reasonable cross-connections between the paths.", we a visual be more better? please attend to your health more. i await your reply and welcome to the new year.

jdrueckert commented 4 months ago

sorry for my late reply, hope you are better and ok regarding your health.

No worries and yes, I am better, thank you :slightly_smiling_face:

about horizontal design rather than vertical design, the horizontal design we be much better for mobile

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.

about the icons, fontawesome can indeed be use, but my main aim was to show you the design i came up with.

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.

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.

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.

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.

I mean a link to the already existing troubleshooting resource we have (see https://terasology.org/Terasology/#/Troubleshooting and subsequent links)

regarding the FAQs, if is not there yet, it can be removed.

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.

Is module more relevant to players or developers.

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.

regarding the installation guides, since is more about world and server setup, then a link to the Terasology launcher docs we be more better.

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.

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.

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. With Java being a very widely known and used language, I think the "type of language" is clear to everyone except for somebody that still needs to learn programming. And while I'm always interested in being inclusive and approachable for everyone, I don't think Terasology is a good first project for somebody that hasn't coded a single line in their life yet, so I don't think we should focus on that group of people when designing our dev docs.

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 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.

"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? consider building up a tree-style structure indicating which docs can be accessed via which paths (basically how a doc reader would click through the different levels) and take care that the paths don't get to long and that there should be reasonable cross-connections between the paths.", we a visual be more better?

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 :+1:

please attend to your health more. i await your reply and welcome to the new year.

I'm working on that, thank you :green_heart: and welcome to the new year to you too!