[haiku-web] Re: [new feature] New way of maintaining developer documentation

2009/3/12 Jorge G. Mare <koki@xxxxxxxxxxxxx>:
> Hi Meanwhile,
>
> . Meanwhile . said on Thu, 12 Mar 2009 07:28:17 +0800
>> > I don't think there is a general rule that menu blocks have to be
>> > on
>> > one side or the other of the body text; it is more a matter of how
>> > the
>> > website has been designed (ie., the Gnome user guide has the
>> > navigation
>> > menu to the right).
>> >
>> > Shijin was designed to have navigation blocks on the right side;
>> > putting
>> > blocks on the opposite side only on some pages is not only weird,
>> > but
>> > it may also break the page layout rendering, as the left column is
>> > not
>> > taken into account in the theme (even when the left region exists,
>> > that's just a remnant from the spreadfirefox theme that shijin was
>> > based on).
>>
>> There is however such a thing as a universal F-shaped reading
>> pattern,
>> which more or less asks for navigation blocks to be on the left.
>> See: http://www.useit.com/alertbox/reading_pattern.html
>
> I have seen many (and read a few) of this sort of studies over the
> years, but in most cases they are geared towards understanding how the
> reader skims through complex layouts with multiple types of information
> that compete with each other, which is not the case here.

Well, like I said, let's just try some things. Like I said in an
earlier message, for me putting it in a standard block on the right
did not feel right. Maybe a nonstandard block does work.

> The content on technical documentation is very focused and the
> navigation quite simple, so the impact of not following such reading
> patterns is negligible. Switching navigation the position of the
> nagivation relative to the content from one side to the other as the
> user goes from one part of the website to another has a more
> detrimental effect.

I *feel* that when reading something like documentation, you are more
likely to look on the left than on the right, because our user
interface is left-to-right oriented. At least here in Safari, tabs are
added from left to right, the menus in the menu bar are from left to
right, the controls are on the left side.

Reading documentation has a different goal than other actions on the
website. The blocks on the right have various purposes, some give
related information (in case of the GSoC block), some are more
distantly related. This is good, because when you are reading a news
post, a blog or a svn log message, you are looking for bite-size info.

When browsing through the docs you have another purpose, you are
trying to learn something. With this, I think left-right orientation
works better, because the important element, the overview, is more to
the left than the content. There is also little use in leaving the
other blocks on the right, since you are actively using the
documentation and you are explicitly not interested in any other info.

Anyway, let's try something.

> Drupal Book's feature is nice for something like the user guide, where
> you have a structure and the book navigation block becomes your "table
> of contents". On the other hand, I am not sure how Nielx plans to group
> or organize the existing loosely categorized documents on the website,
> and what sort of navigation he is planning to provide.

What I think the main website should be is stay in line with the
original intention of making it the center page for developers that
either are involved with Haiku, that are using Haiku, or that want to
get to know/experiment with Haiku.

Let's say we have two groups: haiku contributers and people who
develop for haiku.

Both of them need to Get started. We have several (some outdated)
tutorials on how to build and install Haiku. Let's combine these into
a book where you can learn everything from compiling (on different
platforms) to installing (on different media). Or how to customize the
build process with all those fancy but overly complicated (personal
opinion ;-) build profiles.

Now the Haiku contributors want to read some docs and tutorials on the
sub systems. There is a nice tutorial on unit tests
(http://experimental.web.haiku-os.org/documents/dev/unit_testing_part_deux),
some about the internals of the kits, some about special dev tools.
How do I use these? Grouped together in one (continually updated book)
I can start my Haiku career.

Finally, the developers for Haiku want to hear about the nice
tutorials like how to develop an IME aware app
(http://experimental.web.haiku-os.org/documents/dev/developing_ime_aware_applications)
or how to use TLS
(http://experimental.web.haiku-os.org/documents/dev/lets_make_use_of_thread_local_storage).

Now there will be some documents left (such as how to build the Webkit
module). I don't know what to do with them yet. It is possible to keep
the 'Developer doc' doctype, and leave these under the documentation
pages, or we could create a 'Misc' book and make them editable by
everyone. Or we might even make the Doc type editable by everyone and
by this go with a compromise.

This is how I imagine it how it could potentially be.

Now I am going to leave the stage to Urias and Bertrand (iFrodo), who
in a Trac ticket offered to work on the documentation.

Kind regards,

Niels
-----------------------------------------------------------------------
haiku-web@xxxxxxxxxxxxx - Haiku Web & Developer Support Discussion List

Other related posts: