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

Niels Reedijk said on Thu, 12 Mar 2009 17:22:18 +0100
> 2009/3/12 Jorge G. Mare <koki@xxxxxxxxxxxxx>:
> > 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.

<snip>

> Anyway, let's try something.

Sounds good. :)

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

Just a couple of general observations...

I think a book with a finite number of docs to cater to the main 
audience is a good thing. It is more manageable, and it will make it 
easier for people to find what they are looking for. It will be easier 
to translate too. ;)

I am not sure there is a good way to group the other docs; perhaps 
rather than trying to group documents into books, it may be better to 
create a few broad categories (using taxonomies) and have a list view 
of all documents with a taxonomy filter and a search box so that people 
can narrow down the list by taxonomy and specific keywords they enter 
into the search box. I know this is possible in D6 (I have done it), 
but don't know if it can be done in D5. If this is something you would 
like to pursue, I could try it out on the experimental site for you 
guys to take a look at.

Cheers,

Jorge

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

Other related posts: