[[LeeO]]: I'm not sure that yet another category the best solution considering what is already available between the [[Howto]]s, the [[FAQ]], the "Hieraki Manuals":http://manuals.rubyonrails.com/ ands even ProblemBase. Similar issues of organization were discussed here ProblemBaseDiscussion. Your thought?
The reason I introdiced the [[Manuals]] section was to address [[The 'Middle' Documentation Problem]]. That problem is essentially that none of the existing documentation helps people to understand the way things work in Rails. About the existing categories:
* Howtos are great, but they are about achieving something, not understanding it.
* FAQs are good, but aren't the place for "extended answers". FAQs should primarily link to other pages. IMO, a FAQ descerves its own software (and there's a website devoted to Rails FAQ). It also needs a dedicated maintainer.
* Hieraki manuals are for articles/books, not for small items addressing a particular issue.
The name "manuals" as I coined it is probably a bad choice. However, the "middle documentation problem" is a real one and deserves a first-class solution. I really like the way howtos are presented on the home page, and think a similar effort should be made for "understanding"-type pages.
The ProblemBase is a decent idea, but it's not made prominent, and it's based on interaction rather than creating good document fragments.
My suggestion:
* Rename [[Manuals]] to "Understanding..."
* Rename DevTestProductionManual to \UnderstandingDevTestProduction
* Continue producing documents that address issues of understanding Rails, named "\UnderstandingFooBar", etc. These should have "category: understanding" in them.
I'll leave this here for comments, and perhaps make these changes tomorrow. I'll head on over to DocumentationDiscussion now to see what I can glean, although I thought that was about tools (e.g. next gen RDoc, rather than wiki documentation structure).
-- GavinSinclair
As well, the name "Manuals" conflicts with subdomain for the Hieraki Manuals : http://manuals.rubyonrails.com/
[[MikeSugarbaker]]: That raises the following questions: Why is the top page of manuals.rubyonrails.com not editable? At the very least, can we get the most recently created manuals at the top of the page, and maybe compress the layout so more manuals appear above the fold? And why do we have two different wikis running on two different code bases to document Rails, when one wiki with the capacity for both hierarchic "books" and atomic pages could be developed quickly?
[[LeeO]]: manuals.rubyonrails.com is the Hieraki index page. It is software generated. Maybe newer version of Hieraki allow you to change the order of the "bookshelf" (index page).
http://documentation.rubyonrails.com/ is intended as the user facing main documentation page. It is updated by the website manager(I'm not sure who that is).
There are three (formal?)systems in use for documentation:
# "RDoc":http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/ generates the API documentation
# This wiki is based on "Instiki":http://70.84.29.148:2500/instiki/
# "Hieraki":dev.hieraki.org was later developed and put into use. It is seen as a superior medium for larger documents and cohesive collections(ie. books) that benefit from a fixed structure. I don't know how well suited it is for more general wiki-like behaviour.
[[MarkusQ]]: A further (though related) concern: the concept of a "manual" as a wiki-page introduces granularity problems. Ideally, a wiki-page should cover a single (small) topic completely or a single (larger) topic by reference to numerous smaller topics. This makes it easier for other pages to link to the information (since it isn't burried in the middle somewhere), which is good for all the reasons [[DRY]] is good:
* Effort goes towards doing new things rather than doing things over
* The documentation is less likely to contradict itself
* Errors are more likely to get caught (if a point is only made one place, more eyeballs will check it).
* When details change, they only have to be fixed in a few places
* Explanations can be more throurgh (better cross linkages, examples, etc.) then if they were written from scratch each time.
Plus a few more:
* Simply navigating the wiki teaches people about the structure of rails
* Smaller pages are less daunting to read and to write
* Smaller pages are easier to find (less likely to contain arbitrary combinations of keywords).
* Smaller pages make it easier for readers to change direction (see [[The 'Middle' Documentation Problem]])
%{color:green}Question: is there (and/or should there be) an easy way to link to the other documentation "in the abstract" (e.g. something like RDoc:A_class::function)?%
* No there isn't. Manual authors should include links to the API documentation (and other places) where appropriate, but there is no shortcut for doing so.
* [[LeeO]]: I'd love that. The problem I see at the moment is that the API reference doesn't use predictable and stable links to method names (they're just sequential numbers, which change release to release -- It's an RDoc thing) One goal listed on DocumentationDiscussion is to have PrettyURLs, which would make wiki -> API links alot easier.
%{color:green}Well then, is there a *standard* source to link to them?%
* http://rails.rubyonrails.com ?
%{color:blue}Who is responsible of confirming signups to the Hieraki section? Who can write such a manual in Hieraki?%
* Any approved author can approve other potential authors. Any approved author can create a new book or edit/add-to any other book.