[documentation] How to get more people involved with documentation

[Charlie Lowe]

Luiz wrote:
> 
> The problem is book page is based in "child-links" on "father-links", 
> and now we perceive documentation is not well made making this manner. 
> This structure makes the links "prisioners" each others.
> 
> I think the nodes (links) on documentation must be "free", and both 
> following ideas 1)to use html pages "builded on hands" to "join" this 
> pages or 2) to use a simple wiki are the best ideas than use of book pages

I think I have to disagree that wikis are somehow inherently better than 
the book module for the reasons you are giving. Effective instructional 
documentation and technical manual wikis that I have seen have some kind 
of primary organizational structure. When wikis aren't effective, I've 
seen pages that are sort of hanging out there in the netherland, outside 
of any overall structure, pretty much lost to the user looking for their 
content.

On the other hand, one advantage of the book module over a wiki is that 
a page creator must choose where to put new documentation within an 
existing structure and can still link to other pages as well. This 
prevent those rogue wiki pages that I mentioned earlier; the author is 
one person who should be attempting to do this since they wrote the page 
and supposedly saw a need for it. Moreover, it also encourages the 
author to create pages which fit in the context of surrounding pages. 
Or, as is sometimes the case, we see people volunteering to reorganize 
and rework an entire section to make their content fit. Either way, 
documentation gets improved and structure is always considered, unlike a 
wiki.

Now this doesn't mean that the current documentation structure doesn't 
need improvement. The documentation has grown tremendously over the past 
couple of years and will continue to do so.  Any documentation with this 
kind of growth--wiki or book module--needs constant attention.

Besides, the idea that the parent/child, top down, table of contents 
style structure for documentation doesn't work sort of ignores all the 
effective print-based manuals which must rely on that type of 
organizational structure.