Gentoo documentation not only provide documentation but also hints on what a user would like to do next. Without them, user is just lost and unaware of basic next steps. (french version as english documentation now is affected by the problem) http://www.gentoo.org/doc/fr/index.xml?catid=desktop -> Provide link to the guide and a little text that show a possible next step user will want http://www.gentoo.org/doc/fr/guide-localization.xml Ce guide devrait vous aider à adapter votre distribution Gentoo Linux à n'importe quel pays européen. Bien que le guide originel soit allemand, il m'a semblé judicieux d'utiliser à titre d'exemple un système français. Ce guide comprend aussi la documentation permettant d'utiliser le symbole euro. Now if you really want to move documentation into the WIKI then alter the gentoo documentation as : http://wiki-link-to/guide-localization Ce guide devrait vous aider à adapter votre distribution Gentoo Linux à n'importe quel pays européen. Bien que le guide originel soit allemand, il m'a semblé judicieux d'utiliser à titre d'exemple un système français. Ce guide comprend aussi la documentation permettant d'utiliser le symbole euro. Right now, if user don't know what "localization" is that little help text and link from the documentation will gave him hint on why he should follow it : adapt his gentoo to his local language. Of course, i would have been happier to produce a better example : gentoo and UTF8, but the documentation for UTF8 is delete But previously gentoo doc was link to UTF8 and the little help text was telling user why he should use UT8. Without that link and helper text : how could you expect a user that don't know what is UTF8 do search UTF8 inside the wiki ? Another example : a user seeing in the gentoo documentation : nVidia guide for gentoo : (on the fly translate from french) : Many gentoo users own an nvidia card. Nvidia have specific drivers to boost performance of your card. That guide will explain howto build and install those drivers. Change the link to the nvidia wiki then, but removing that entry from the documentation will do that : Because i know i own an nvidia, this "helper text" just shown me "hey there's something for you that will help you, read this". And without it (like it's currently going on) : sure the WIKI have the nvidia entry, but i'm just unaware of it and i don't have the need for it, until someone tells me i would benefits from it. Reproducible: Always Expected Results: - Keep gentoo documentation helper text that hint new users what are next logical steps to do. - Instead of removing the documentation helper, update it to point to the WIKI article reference.
Hi Stéphane I understand the complication it brings, but we cannot update the list easily with the pointers. That page is dynamically generated based on the meta information from within the XML documents, so the moment these documents are moved to the wiki, the page cannot refer to them anymore. When the migration is done, we might have a new overview page available for the documentation, similar to the previous one, but that's still under consideration. For now, a good place to be would be on the main wiki site and using the search functionality, or browse through the categories.
Why not add the overview page now, or keep "old" documentation alive until the move is done. I suppose the documentation move will takes time, and in the meanwhile user doesn't have access to the "overview" page and the gentoo documentation is getting worst as doc are been removed. I agree this is temporary issue : once move is done and overview page is built everything will be ok. But i won't bet on the time need for "move is done".
Don't take it wrong, i'm happy as now i know a feature won't disappear and will be put inside the "overview page". This was my main issue. But the transition could be made "less dirty", if the overview page was up and update when a doc is moved to the wiki.
(In reply to Sven Vermeulen from comment #1) > Hi Stéphane > we might have a new overview page available for > the documentation, similar to the previous one, but that's still under > consideration. grrr, hell forget the "might have an overview" :( Could you cite that bug as argument for "consideration".
Keeping the list alive would mean potential duplicate work (changes on the XML made done after migration would need to be ported), and creating the overview page now means that the documentation remains on gentoo.org much longer; I'm one of the few people still working on the documentation, so the sooner I can migrate documentation to the wiki, the sooner the community can assist in keeping the documentation up to date. Without this, bugs keep piling up :-( The reason why it is still in consideration is because there are multiple "ways" to have an overview page (technically) and I'm not sure which one would be the best, if one of them is. So if you have an idea on how to create a decent overview of qualitative wiki pages, I'm all ears. Right now, I think that those documents on the wiki that are translatable are qualitatively stable. There is an overview possibility, but it's not structured (beyond alphabetical order).
The previous presentation was doing the job. So the same inside the WIKI will do the job. And a note inside the gentoo documentation pointing to that overview. Installation Related Resources Gentoo Desktop Documentation Resources ... Then : (Gentoo Desktop Documentation Resources sample) Gentoo KDE Guide: This guide demonstrates how to setup KDE SC using the ebuilds in the tree. Some tools from the KDE team's git overlay (kde) may be used. The Xfce Configuration Guide: This guide provides an extensive introduction to Xfce, a fast, lightweight, full-featured desktop environment. ... That is perfect imo : someone who don't know what KDE, XFCE... have now clueabout them (as it's in Desktop section) and can click on their link to get the KDE wiki article (or put KDE in search button, anyway user now knows KDE is the name of a desktop). But i think it would be more appropriate to use a cleaner view for multiple doc like that : Xorg Upgrade Guide : This guide shows... And a link to general Xorg upgrade guide, that will have links to specific xorg version in it. This way the xorg upgrade index need update, but overview will remain unchange if any new xorg upgrade version article is built. Than the previous version that was putting all links as : Xorg 1.5 Upgrade Guide: This guide shows you how to upgrade X.org to version 1.5. Xorg 1.6 Upgrade Guide: This guide shows you how to upgrade X.org to version 1.6. ...
When i say "gentoo documentation" i speak about http://www.gentoo.org/doc/en/ vs "wiki" (to make it clearler as gentoo documentation can/is/will be in the wiki). It's just to differentiate their location. So "And a note inside the gentoo documentation pointing to that overview." per example in my mind mean : http://www.gentoo.org/doc/en/ updated with You can get at update documentation at https://wiki.gentoo.org/wiki/Overview I'm sorry using the term "gentoo documentation" to refer to the location of the doc at http://www.gentoo.org/doc/en/ could had put confusion and was only clear for myself.
Hi Stéphane Yes, but the problem is that with XML, this additional information (the "abstract" of the document) is metadata available within the XML file. As such, we could easily add it to links. With wiki documents, this abstract is gone (well, we put it as the first paragraph of most documents, but that is a convention, not a rule or policy). In order to generate such an overview page, we might need to write a customization on the wiki to do so. Such customizations are much more difficult than parsing of XML files.
Overview need to cover basic steps that are high needs for everyone AFTER gentoo is install: installing a DE, drivers (common one, like nvidia, ati, wireless...), localization settings, UTF8... And not covering "advance" usage, as this time, user will be of another level and you can bet he knows the tools he wants... and can seek them himself in the wiki. So that can be a manually made overview. The purpose of the overview is not trying to show all possibilities of gentoo, but to not lost the help that was provided to someone unaware of nix system and drives him to first tools he should have a look at. (remember after following the handbook, if he success, the user just have a prompt, no DE, and he still needs to configure plenty things, localization...). And any gentoo users can do "emerge gnome", but a new user that has never use gentoo won't be aware of "emerge", and one that comes from Windows might not even knows "gnome, kde and their friends...". We shouldn't leave such user dead with their prompt and no clue on what to do. So that overview page might just be a "getting start/what's next" page if you prefer. User aware of nix or gentoo need less help and the search function or category of the wiki would be enough for them. So, user install gentoo and then at handbook end, he is drive to the overview page. ps: after writing that, i suppose it could also be just add as the handbook last section without need for a special page. Have a look at https://bugs.gentoo.org/show_bug.cgi?id=18651 Yep, documentation was lacking to tell "nano" is an editor by that time, not knowing the tool name is a blocker for a starter.
http://blog.siphos.be/2013/12/majority-of-gdp-documents-moved-to-gentoo-wiki/ :D :D :D Happy Might be valuable to add this link in the Overview: http://wiki.gentoo.org/wiki/Recommended_applications I'm aware the extra work Overview page has put on you, i was sure it was worth the effort, but seeing it i'm pretty sure now everyone could agree with that. It's even better than the original page ! I find it more clear and easier to use (the one page to fit all is sure a nice improvement, as you get everything without need to click subsection like it was). Thank you.
