[documentation] the documentation site is too broken and lacks formatting and writing style

[Djun Kim]

Good points, Robert...

On 13-Jan-2006, at 4:59 AM, Robert Castelo wrote:

> For me the two highest priorities for the handbook are:
>
> 1) being able to find the right page
>  - increasingly difficult now that we have so much documentation

     agreed...


> Breaking a page up into small sub-pages makes it more difficult to  
> find the right page through a search engine, which rates the  
> relevance of a page by keywords appearing in headings and sub- 
> headings and also how often the keyword appears throughout the page  
> - I think this also applies to Drupal's built in search engine.

      I would think that a smaller, more focused node
would be more 'relevant' than a larger node which
contained multiple topics.   Hence searching
would be easier, both from the point of view of
the search engines / search module, and from the
point of view of the user.

> 2) readability of the page
>  - how much effort is required to read everything on that page

     again, I think we all agree here.

     The challenge is finding the right middle ground
between throwing everything at the user and having
her sift through it, and presenting only one atom at a
time, thereby losing visual context and forcing
hunt and click navigation.

> Obviously scrolling down one page is a lot less work than locating  
> and clicking through x number of links, this becomes specially  
> important for users with degraded motor skills and the visually  
> impaired.

      Up to a point.  Either extreme could be annoying.
If I had to rely on a screen reader, I think I'd be
annoyed at excessively long, linear texts.

> If there's a problem exporting markup with sub-headings, could we  
> not deal with that at the code level, parse the output and break it  
> up into sub-pages on export?

     The approach I've been contemplating is the opposite -
presenting a given node as a page in the context of
the linear neighborhood of its surrounding text - just
like reading a book.

     So for example, three short sequential subsections
would appear on the screen as three chunks of text
introduced by three headings.

     This would 'look' like what we want - text in context -
but preserve the structure we need for export and
content reuse.

     Cheers, Djun