From mboxrd@z Thu Jan 1 00:00:00 1970 From: Timo Eissler To: documentation@lists.ipfire.org Subject: Re: Restructuring of the hardware section (i.e. removing duplicate/obsolete stuff) Date: Mon, 09 Feb 2015 10:08:38 +0100 Message-ID: <54D87916.3050501@teissler.de> In-Reply-To: <1423400748.2329.43.camel@rice-oxley.tremer.info> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="===============2504960758635935244==" List-Id: --===============2504960758635935244== Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Hello, except the point that we should have (if i understand you right) a english and a germin version of all pages i'm totally with you. In my opinion every IT related person should be able to read english documentation. But i understand that home administrators may also want to benefit from this great piece of software and aren't able to read english. So i think we should take a decision for maybe max three languages on which we take care that everything is up to date. If i had to find something in the wiki i often feel like... *Argh* why couldn't i find this page, i know it was in here some time ago... So i too think we should define a clear structure of how to organize our knowledge. And too not confuse people, we should move everything outdated away, maybe in an outdated section but not in the trashcan. I agree that outdated information is useless in the presence, but maybe it could be useful if you are in front of an ancient system. Kind regards, Timo Am 08.02.2015 um 14:05 schrieb Michael Tremer: > Hello, > > I am writing this to you just because things need to be said. It might > be that not everyone who reaches this email is the right person who > should read this, but nevertheless I am annoyed. > > I am deeply annoyed with the state the wiki is in and I have been > annoyed for a long long time. There is so much documentation in there > that is either in a bad state, is completely outdated or is now just > wrong. > > I often stated that I am willing to tolerate if there is information > missing in one or the other of all the languages, but when it comes to a > point where people are more confused by the documentation than it helps > them... we need to do something. > > Last night, I restructured the entire hardware section. It was really > bad. Especially information about the various ARM hardware that is > supported was all over the place. Some pages have been there twice with > completely different things on them. Some had their own section. > > The result of that is that the landing page of the hardware section > (http://wiki.ipfire.org/en/hardware/start) was stripped to the bare > essentials in my opinion. What are the requirements? What hardware > should I use? Examples? Done. > > Some things that have been on the very long page before were just moved > to a sub-page. I find it very important to explain why certain decisions > where made and what reasons are behind something. But having all that on > the first page is not helping. People don't read long texts if they are > searching for a particular thing. If someone is interested in more > detail he or she will search for that any way. So the landing page shows > the recommended hardware specification. All other information about that > can be found over here: http://wiki.ipfire.org/en/hardware/requirements > > Then I created a section which just handles the ARM hardware: > > http://wiki.ipfire.org/en/hardware/arm/start > > As mentioned before, there is no new information. This is just all the > information collected from the rest of the wiki and restructured. The > key element here is a table with all the hardware we support (or > explicitly do not support). I figured that this is the most important > information that the users are searching for. If you click on one of the > boards, you will find additional information. Those pages are not the > best and explain how to install an ARM board over and over again. That > is good for now, but needs to be cleaned up as well in the near future. > > I am telling you this because I want you (who ever is interested) to > understand what I have in mind when I write these things. It may not the > best thing, but I have some points why I am doing it like I do it and > may be you can adopt some of them, too. > > Clean design and clear structure is hugely important. This wiki holds so > much information about IPFire that almost every questions can be > answered. The problem with that is that it is very hard to find at > times. If you know what you are searching for you will find the right > page very quickly. If you are searching for something for the first time > with no background information, you are practically screwed. > > > So to bring this all to a point: I am very much inclined to delete huge > parts of the documentation. > > > I find it much better to have no information at all instead of providing > the users with wrong information. Wrong could also mean just outdated or > obsolete. > > A few examples: We don't need pages which say "English version coming > soon". This has been there since 2013. > http://wiki.ipfire.org/en/addons/virtualisation/howto/debian_wheezy_xen_4.1 > > We also do not need installation guides for outdated software (here > Debian). If anybody is going to install a virtualization host, they > should certainly start with the current stable version. So either this > needs to be updated or removed. > http://wiki.ipfire.org/en/addons/virtualisation/howto/debian_xen_4.x > > Why did someone even start writing a separate page for Wheezy (only in > German) when there was already a page about the same topic with Squeeze? > I imagine this has happened because the author was unaware of the > existence of the one page. > > This is just one of the many examples I can bring here and I should > point out that I am not at all disappointed with the work many people > have done here. There is only something massively wrong with how it is > maintained. Outdated information isn't worth a penny. > > There is a third page about the same topic handling Debian Lenny. > Someone added a notes that this page is outdated. At this point I cannot > imagine something else but deleting all of this. > http://wiki.ipfire.org/de/addons/virtualisation/howto/debian_als_dom0_xen > > > The other topic that is the missing translation is the firewall section. > Since almost a year now there is a completely rewritten firewall GUI. > Nothing looks the same any more and some parts have become more > difficult to use. Hence we wrote a very decent firewall documentation > which no one ever translated into any other language. > > It has been pointed out several times on the forums and many people made > promises to actually do something about it. No one ever did. It was not > even started. > > I cannot help it thinking that there is just no interest in having a > German translation. Many people argue often that it is important to keep > documentation accessible in various languages and I completely agree > with that. But if nobody cares doing the work I can not take you and > your point serious. > > I am especially picking on the German translation as we have a huge > community of people who are speaking German. The translations of the > other languages are not very much advanced so that people don't read > these at all and even if they do, there is not so much outdated > information in there (the installation works the same since years for > instance). > > So in the end there must be consequences. I am not sure about what is > the right way - quite possibly is there no right way of doing this. But > seriously guys, we cannot keep doing this in this way we are doing it > right now. That is dangerous. > > I wonder if someone has something to say about this matter. I would be > happy to hear from you all. There are over 50 people subscribed to this > list. So I will take silence as an answer. > > Best, > -Michael > > _______________________________________________ > Documentation mailing list > Documentation(a)lists.ipfire.org > http://lists.ipfire.org/mailman/listinfo/documentation -- Timo Eissler Senior Project Engineer / Consultant Am Zuckerberg 54 D-71640 Ludwigsburg Tel.: +49 7141 4094003 Mobil.: +49 151 20650311 Email: timo(a)teissler.de --===============2504960758635935244== Content-Type: application/pgp-signature Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="signature.asc" MIME-Version: 1.0 LS0tLS1CRUdJTiBQR1AgU0lHTkFUVVJFLS0tLS0KVmVyc2lvbjogR251UEcgdjIKCmlRSWNCQUVC Q0FBR0JRSlUySGtXQUFvSkVFbVJDWjYzY3RFdHJNVVAvMXFQNXFaQXZUWEpxOUxuVno5MHdXeG8K OXhVdW5xak9mQU80WDJyejFha0tXMUJiRzZEdE1RQmtibGZ4UEFIaCt5N29hTTJ5d2lvRUxGLzlN aHdxMldXZApNRTFnS09JUmNnVng5Y2F2TzJCSktyMGdXbHVBakU3U21rZU5hd2RGWVBmTmY0S2c1 WHl1R2t5Uzd3cC9MQWJwClU0dS9Fa2c1bkM3eTNSQXppVDk1eEFVS3JNbGVrVDZxODF1VDRFbjBk UkF6MkJ2b1F0Q3l0UFZYWHJGVFdLaFoKTTVuVy9GVnpWYko3QlpTbHorNkJOY2ZSemdsZk51S05U WlU5RnN6bE5pZ3owZFFXNmIvRXJDK1lKeDk0SUpiQgpLdXlKM2FTOVdUeTdxRExxMVNvQTIveFpW clQ2OVgxZ1c5NlBuaVlhck8vcG1kYk9TWEhOcjlHQWdEdHlvNzdNCnMzWWFNSjlyN1duSklrQnhH Z3ZMWlZ2THZvbWUxc0o2TDQxL1Q3czFuaFZ5WjdXUEZOMFVIVURYa0oxV3FPQ0EKMlBlMFF6ZzhI T1p0SEE5MnJvQ0VCRHpoWlpnR1dlRXNiSGNPSnJXcENVVGpBREFyaU9hZlRHVzVRYVZhVkZ6Lwor eEE2WlkyWTV0RGlINngrdTNaeEp1cVpIVys0MmtmczZtSWJyVG9NUEMyVVNUdWJYbGpSbnI0T3R2 OVR3ZS9LCk1YdkIxZ3Zla21HeG0xWFZkamUrL0Vtb0FBNjhXcU5saHhJOVBETXRkR2ZLOXg5WXZt ZHphbEN5NmFaOWQ3M1EKaHBxZHkxN1ZhV3RWSEMzTEFQUGlYQlRFWTkybXFzNDBiWTVINkNPRURh UCtuSmtiZzFZRCtXaE0yd0ZKc2YvMgprckgxK0tuNWwvanJoVUhZd2ZWeAo9cm5pbwotLS0tLUVO RCBQR1AgU0lHTkFUVVJFLS0tLS0K --===============2504960758635935244==--