[haiku-doc] Re: Reorder sections of the user guide
- From: "Humdinger" <dmarc-noreply@xxxxxxxxxxxxx> (Redacted sender "humdingerb" for DMARC)
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Fri, 05 Jun 2020 08:32:01 +0200
Hi Kacper!
On Thu, 4 Jun 2020 21:15:36 +0200 Kacper Kasper wrote:
The troubleshooting section on the Boot Loader page should IMO
remain
there, as it's directly linked to the failings of booting and
possible
solutions.
Sure, but maybe we should have Troubleshooting article linked from
the
ToC, sort of FAQ.
Maybe we can come up with something more general and not Boot Loader
specific in the future.
Having Boot Loader first always seemed natural, as it's the first
thing
a user sees. Putting it last might 'hide' it from users whose boot
problems may be solved by it.
No, a user sees loading screen, and probably doesn't even consider it
a significant part of the system.
Users may wonder what the icons lighting up mean (and why it's stuck on
one, and how to solve it, when Haiku doesn't like their hardware). But
I don't want to belabour the point. Off it goes to the the last entry.
Also, over 50% of the article is listing options and their
descriptions, which is not that useful, since when I'm in the menu, I
can see them, and I believe the descriptions are there too.
Some do elaborate a bit. Also, it does help people that don't speak
English.
Don't get me wrong - having that is useful, but as part of reference
book, not user guide.
I see the user guide as something of both.
Not sure what's the mass closing by advanced methods is about.
I mean killing teams and using keyboard shortcuts in Twitcher to kill
apps/close windows.
After Deskbar, I have one method to manage windows at all. Other ones
are not as important anymore.
How to use the Twitcher to quickly switch between apps/windows is
important. A poweruser on IRC recently didn't quite get how our witcher
worked, even after reading the guide. I tried to improve the wording to
make it clearer...
Additional info, like that you're even able to hide windows and quit
apps with it, are very nice to have. When someone bothers to read up on
a component, why not show them also the more hidden features?
A few years back we explicitely added all the direct links to
Applications/Preference/etc. because people would look for a
specific
app's doc and couldn't find it...
Sigh, "more..." should solve that problem. I can understand that it's
not obvious to click Applications to get a list of them (seriously),
but I suggest to cut that list to 5/10 essentials, with that "more..."
at the end. Does TV deserve to be in ToC?
Apparently, the single link to "Applications" was too easy to miss. If a
users likes to know more about app X, he may scroll to the list of
applications and have a look. Or, if they are a 'poweruser' like me :)
, use ALT+F to search the page for it.
The list should contain:
ActivityMonitor
DeskCalc
DriveSetup
Expander
HaikuDepot
Installer + SoftwareUpdater
Mail + People
MediaPlayer
Screenshot
StyledEdit
Terminal
TextSearch
WebPositive
ShowImage did not make the cut, because it's discovered as soon as
you
click an image file. That would probably happen sooner than going
through User Guide.
It's not really about discovering applications, but to learn the details
of their usage. With ShowImage, users happen on it very naturally, as
you said. If they seek more info on it, they won't find it among the
apps listed when they open the user guide.
Same goes for the more technical apps like DiskProbe and DriveSetup. If
anything, those apps may be more likely to be the target of reading up
on in the user guide... Just saying, it's not so clear cut what to
include on the entry-page and what not.
Hmmm... what do you think about showing these longish list of
applications and preferences in two columns? Would cut their length
onthe page in half.
And then, Bundled apps are not listed in ToC, but are way more useful
and all should be listed: BePDF, Pe, Vision, WonderBrush
Maybe. OTOH, aside from Vision which doesn't have that great docs, we
just point to those bundled apps' documentations. But, I'm not against
that small addition.
(BTW we
support x64 officially now, and it's not available in that build I
think - that should be mentioned).
I kept hoping this issue would have been fixed until our next release...
:)
On that topic - Magnify is important, but it should end up in a
separate Accessibility section.
Originally, those lists - apps, applets, preferences (one day
'demos'...) - were to reflect those groups in the Deskbar. Magnify being
the only accessibilty app AFAIK, may be lonely in its own section. :)
Also, I always thought of Magnify as mainly a developer's app to count
those layout-defying pixels... but I suppose it has other usages too.
To back all that up I'd like to point out that the first sentence of
"ToC" says: "Below, you'll find the documentation of *the most
important* aspects of Haiku." Also, ToC is not an index.
Well, it can be both. It may have to be as there is no separate index.
:)
Anyway, how about this then:
Haiku's GUI
Deskbar
Tracker
Applications (2 columns, + link to bundled apps)
Workspaces
Twitcher
Team Monitor
Shortcuts and key combinations
Desktop Applets
Preferences (2 columns)
Queries
Filetypes
Attributes
Index
Filesystem layout
Workshop: Filetypes, Attributes, Index and Queries
Workshop: Managing Email
Workshop: Wireless networking
Bash and Scripting
Boot Loader
Regards,
Humdinger
--
Help translating 3rd party Haiku applications
Go to Polyglot at
https://i18n.kacperkasper.pl
Other related posts: