Summary: | Separate architecture-specific instructions dynamically | ||
---|---|---|---|
Product: | [OLD] Docs-user | Reporter: | Aaron Peterson <alpeterson> |
Component: | Handbook | Assignee: | Sven Vermeulen (RETIRED) <swift> |
Status: | RESOLVED FIXED | ||
Severity: | enhancement | CC: | clippyhater, dberkholz, docs-team, kumba, m.debruijne, sparc |
Priority: | High | ||
Version: | unspecified | ||
Hardware: | All | ||
OS: | Linux | ||
Whiteboard: | |||
Package list: | Runtime testing required: | --- |
Description
Aaron Peterson
2004-02-24 16:26:50 UTC
The solution (if any) should really be a bit more generic, allowing for the links/lynx users to be able to hide the architecture-specific instructions too. Please join gentoo-doc@gentoo.org (gentoo-doc-subscribe@gentoo.org) and contribute to the current ongoing discussion: http://news.gmane.org/gmane.linux.gentoo.documentation, thread "Separating architecture-specific instructions from Handbook" The requirements: http://article.gmane.org/gmane.linux.gentoo.documentation/1055 I've relied on the Installation Documentation for x86 and sparc for a long time. I seethat the Handbook has replaced all those installation guides that I've _relied_ on for so long. IMHO, the Handbook is not yet suited for most folks looking to install gentoo. Worse, it is difficult to find arch specific stuff. I realize you guys have hard, thankless jobs but could you _please_ put the table with the Install Guides (for various architectures) back on gentoo.org? Especially the one for sparc? Thank You, I feel the handbook *is* suitable for installing Gentoo, regardless of architecture. I am not going to reinstate the old guides, sorry. >>It's hard to find [stuff]
>I am not going to reinstate the old guides, sorry.
I think what je_fro is asking for, is just to make the old versions of the install guides available... I don't think he's asking for more development on them.
I know I was up a creek without a paddle when the documentation changed, and I had an old implementation of a feature, and had to go find the new documentation, and figure out what had changed. Having the old versions around (or instructions for receiving the old versions from CVS) would be very usefull.
I know that I stopped using the handbook because I spend so much time scrolling around, missing steps and all. When my gentoo goes unstable, I have been forced to use something else untill it annoys me enough to search through the documentation.
also, the GWN could show a list of packages that are scheduled to change implementation / functionality, so we can be prepaired to change them rather than googling for it when it breaks
Old docs are still available in our CVS at http://www.gentoo.org/cgi-bin/viewcvs.cgi/en/?root=doc In particular, the latest Sparc install guide can be found at http://www.gentoo.org/cgi-bin/viewcvs.cgi/en/gentoo-sparc-install.xml?rev=1.28&root=doc&content-type=text/vnd.viewcvs-markup As a one-off goodwill gesture, I give you a rendered html version at http://dev.gentoo.org/~neysx/tests/gentoo-sparc-install.html Use it while it lasts, I'll leave it there only for a few days. Don't ask for other docs, this was a one-off gesture. Read http://www.gentoo.org/doc/en/doc-tipsntricks.xml?style=printable to learn how to render our xml docs yourself. I agree that "dynamic" separation of the documentation is not enough. If we are going to continue growing, we need to have the documentation be updated by the people who change the functionality... and the dynamic hiding of arch specific information won't solve that problem. I think we should have a database (basically a wiki), with each page being a paragraph, or even sentence!.. or any arbitrarily small content difference... and have the page be glued together. With this system, we could write once, use many, have architecture specific guides be generated, have all inclusive guides be generated, and have the ower of certain packages be responsible for product documentation. we have no need to rewrite the architecture independent portions of the guide for each architecture, we do need to hide extraneous information... Database table: Table_of_Pages page_name page_title page_url page_id page_content (page content can included references to other pages that include other pages) note, page categories could become a class of page_architecture (decide if coma separated or an entry for each architecture, and or have a keyword all.) or page_arch_i36 w/ page_arch_alpha w/ page_arch_ppc w/ page_arch_sparc w/ page_arch_all w/ page_arch_little_endian w/ page_arch_big_endian (a group of all architecures that are this way) w/ page_arch_other_group_of_arches document_categorory_to_document_id Category_name category_id category_document_id this list is not one to one... some troubles arise if there is more than one category to a page note, each page has a content area.. that may contain inclusions of a category or specific page, which includes it's contents... risk of infinite recursion is possible, but should be stoped at 5 layers or less... Category_Product page_id team_category_id (the Category_Architecture page_id architecture_category_id or we could have a category page for each specific archtecture... I'm not a database designer. Each maintainer of whatever program is responsible for vis own section. The content would be in your docbook format, and would be embeded in a container document that has the appropriate headers and footers.. and the content would have some form of markup to denote inclusion of other pages. http://wiki.linuxquestions.org uses the wikipedia engine, which has a sort of method to modify only specific sections of a wiki page... this is similar to what i am thinking about, and it may have the functionality already there... but I haven't seen it... I am very much wanting to make this system... er... have a system like this available. Superman could not keep up with the daily changes of the system. We need a team tool, and we need the people familiar with the architecture to write the actual instructions on how to do things, editors can come and make it pretty.. but pretty doesn't matter, functionality and navagatabilty are important, and having the page full of irrelevant info is contrary to navagability. Using wiki-style approach has its advantages, but it's not the end-of-all-for-you-all tool as it has disadvantages as well. Anyway, please keep this bugreport on topic - discussions should be held on the gentoo-doc mailinglist (or in a separate, on-topic bugreport). *** Bug 46431 has been marked as a duplicate of this bug. *** Drafts: http://www.gentoo.org/doc/en/handbook/draft/handbook-x86.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-alpha.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-sparc.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-hppa.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-ppc.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-mips.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-amd64.xml Fixed in CVS. thanks! the betas looked cool. |