website
website copied to clipboard
haiku
Organized Haiku Guides
- Improved some language.
- Tutorials that are more suitable for beginners and non-technical people are on the top of the site, while the more technically advanced tutorials are now separated.
Note: Although my grandma would have no idea what a virtual machine is, I felt like it was worth keeping it in the "Beginner" section because it really is a good way to try out Haiku without going through any drastic and permanent changes - the documentation for doing so isn't quite that bad either.
The original idea of this page was to follow roughly the steps a beginner has to take:
- Install Haiku (real hardware or virtual machine)
- Get it to boot (boot managers, etc)
- Daily tasks (start using the OS)
- Troubleshooting in case something doesn't go right
- Building Haiku (you're a poweruser now, let's make you a developer)
This makes a nice "getting started" guide to the OS. Some pages (the one about network booting for example) should be moved out of this, and linked instead from somewhere in Documents/ instead. Especially because it's been non-working for a few years now.
This makes a nice "getting started" guide to the OS.
That doesn't quite work. It's mixing complicated subjects that the average user should have no business messing around with with actually useful tutorials. The same thing is sort of being done here, with a stronger thematic separation.
Some pages (the one about network booting for example) should be moved out of this, and linked instead from somewhere in Documents/ instead.
Will work on it. But I shouldn't just move things without a plan and without organization, that's a very bad strategy that will just lead to more confusion because we do not know where exactly the legacy documentation should be moved yet. Approaching one goal at a time seems good for now, although I get that they must be removed urgently because they don't work anymore.
I'm trying to achieve some gradual, partial organization, before I proceed with organizing other parts, but I can't do this completely because different parts of the documentation depend on each other, and I don't have a full plan other than partially re-organizing everything until it all makes a little bit more sense. Throwing everything under Documentation does not feel like a good strategy.
Organization has a higher priority than updating content, IMHO, and the latter will be much more easily achieved if things start getting organized.
That doesn't quite work. It's mixing complicated subjects that the average user should have no business messing around with with actually useful tutorials. The same thing is sort of being done here, with a stronger thematic separation.
If you are focused on users, you should turn your interest to the Haiku user guide: https://www.haiku-os.org/docs/userguide/en/contents.html
This is more a "how to get started with Haiku" thing, and I don't see how you can start otherwise than downloading and installing it. If that procedure is not accessible to users, we should simplify it. Besides the "network booting haiku" which should be removed, I think the guides for installing Haiku in a VM or on real hardware, and to set up a bootloader, are fine here?
Also a little more backstory on this "guides" page. It was created sometime after the website reorganization/redesign of 2009.
Here is how the website used to look: http://web.archive.org/web/20081217115922/http://www.haiku-os.org:80/
At the time there was a pretty clear entry point straight from the hole page: development -> getting started for developers. There was not so much a thing for users (we didn't have even alpha1 available at the time so the focus was really on developers).
With the new design and the need for user documentation, the website organization is a lot less visible than it was then, and it was very hard to find things.
Later on, the www.haiku-os/guides/ page were set up. They do not fit into the existing organization. They are often not linked from other places in the website. Yet the content was useful and so it was kept this way, and people added more and more things there because at least this page has a clear entry point.
Further confusion in the other parts of the website is caused by the fact that we had both "developer documents" in the "documents" section and a whole separate "development" section. No one can tell what should go where.
My opinion on this is that:
- "developer documents" should be moved to somewhere inside the "developer" section
- "documents" should be deleted, and instead we should just put user-related things in the user guide, or have some other more accurately named section in the website (but if it's targetting users and it's not the user guide, I have no idea what would go there)
- The guide pages should probably also be moved into either the development section, or the userguide
Just to chime in, I think we did have a long discussion about the organisation of the website here on the forums: https://discuss.haiku-os.org/t/how-to-improve-docs-related-to-contributing/10047
And yes, I totally agree with what @pulkomandy's proposed - developer docs in the "Development" section, and "Guides" moved to either "Development" or the User Guide (though, having a look now, only the "building Haiku" guide would fit in the "Development" section; the rest are suited to the User Guide.
Regarding deleting the "Documents" section, I wonder - which section the old BeOS newsletters should go? Also, it might be a good idea after moving the Legacy Docs into Development (because most of them, save the newsletters are related to development) to mark them as "Legacy" just so people know.
I think we mentioned in the forums though, that we might have to create a lot of redirects since the abovementioned pages will be linked in many different places on the website - unless we just have a generic "Oops, this page can't be found, maybe try searching for it?" which might not be as user friendly...
I think we mentioned in the forums though, that we might have to create a lot of redirects since the abovementioned pages will be linked in many different places on the website - unless we just have a generic "Oops, this page can't be found, maybe try searching for it?" which might not be as user friendly...
One way to avoid that is to (partially) separate the visual organization of the website from the URLs where pages are exposed. So the URLs for existing pages would remain, but they would be linked from different places than they are now.
I think there is no perfect solution here, creating a lot of redirects is more initial work but allows us to keep things cleanly organized in the futre ; not moving the pages means we have to live with URLs that don't match how the pages are organized ; doing nothing (there is already a "page not found" page) puts the confusion on the website users instead of us.
Just to chime in, I think we did have a long discussion about the organisation of the website here on the forums: https://discuss.haiku-os.org/t/how-to-improve-docs-related-to-contributing/10047
Yeah, I was the one to initiate it and it just got me even more confused. Will try to take a read again.
One way to avoid that is to (partially) separate the visual organization of the website from the URLs where pages are exposed. So the URLs for existing pages would remain, but they would be linked from different places than they are now.
Not a good idea when content is mixed up, e.g. articles being labelled as blog posts and vice versa, or when you find building instructions in the documents section. This has to happen once and be kept that way, I'll have to find a large kanban board somewhere.
doing nothing (there is already a "page not found" page) puts the confusion on the website users instead of us
Also, that's a horrible SEO practice.
Should I just remove the URLs with the outdated instructions and then call it a day, or is the plan to move them to a different part of the website as well?
Is removing it a good idea when there's the prospect of improving it? What happens then? Will we re-add it?
Should we merge the changes in this PR and then discuss any changes to the documentation/website elsewhere?
I wrote a lot of the initial guides stuff. It's definitely wasn't ideal, but was a stop-gap around R1/alpha1 (we got a lot of questions on basic installation steps).
I think a great direction to go with this would be to improve the User Guide documentation adding an "Installing Haiku" section. There we could cover things like how to partition your disks, etc. (aka, stuff we get asked a LOT on)
For Reference: https://www.haiku-os.org/docs/userguide/en/contents.html
That's available in our source code repository at docs/userguide
I think docs/userguide is generated via https://i18n.haiku-os.org/userguide/ ? I don't even know to be honest which is likely part of the problem. I don't have access to https://i18n.haiku-os.org/userguide/ even after ~10 years+ of doing Haiku stuff :grimacing:
If you want access to the userguid translation tool you just have to ask the i18n team. Probably @humdingerb or @nielx can achieve it?
Should we keep the developer-oriented guides in the website, gradually remove the user-oriented stuff and put it in the User Guide and then try to sledgehammer the Guides in the section meant for the Developers? (I have a good idea for the latter, I think. Everything in between is the problem for me.)
Should we keep the developer-oriented guides in the website, gradually remove the user-oriented stuff and put it in the User Guide and then try to sledgehammer the Guides in the section meant for the Developers? (I have a good idea for the latter, I think. Everything in between is the problem for me.)
That was my thought. Definitely agree we need to improve the "user documentation" vs "developer documentation" paths on the website. We could leave developer documentation on the website, and shuffle users over to the user guide.
That makes sense to me since the user guide has a larger audience and is translated to multiple languages and is available on the release media.
Hi Alex von Gluck IV!
On Sat, 03 Jul 2021 08:01:23 -0700 Alex von Gluck IV wrote:
I think docs/userguide is generated via https://i18n.haiku-os.org/userguide/ ?
I don't even know to be honest which is likely part of the problem. I don't have access to https://i18n.haiku-os.org/userguide/ even after ~10 years+ of doing Haiku stuff :grimacing:
I'm pretty sure you have had an account at the userguide tool for a long time. There's a kallisti5 with admin permissions there.
Regards, Humdinger
-- Help translating 3rd party Haiku applications Go to Polyglot at https://i18n.kacperkasper.pl
I'm pretty sure you have had an account at the userguide tool for a long time. There's a kallisti5 with admin permissions there.
Then I lack the password :smile:
Hi there!
On Sat, 03 Jul 2021 10:48:15 -0700 Alex von Gluck IV wrote:
We could leave developer documentation on the website, and shuffle users over to the user guide.
I'm a bit concerned that this could blow up the user guide and even fewer people will read it. Right now it's focused on how to use a ready installed Haiku. If we add e.g. all permutations of how Haiku can be installed on various media, virtualized with half a dozen VMs, booted with other boot loaders, UEFI/MBR/network boot, etc. It might just be too much... Add to that no index or search function. I'm not entirely convinced all user docs should move from the website to the user guide.
Regards, Humdinger
-- Help translating 3rd party Haiku applications Go to Polyglot at https://i18n.kacperkasper.pl
I agree with humdinger that the user guide should be for users of Haiku, who already have it installed, and guidance on how to install it should remain on the website. I think the changes in this PR are good, and if we need further reorganization that can be done later.
Hello, it's been more than a year since I opened this PR, which was supposed to be the first part of a set of improvements that I was planning to make to the website. Is there anything else I can add here?