From mboxrd@z Thu Jan 1 00:00:00 1970 From: Michael Tremer To: documentation@lists.ipfire.org Subject: Re: Restructuring of the hardware section (i.e. removing duplicate/obsolete stuff) Date: Mon, 16 Feb 2015 20:05:37 +0100 Message-ID: <1424113537.17826.69.camel@ipfire.org> In-Reply-To: <54DC5E6F.9030803@dailydata.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="===============8331804221342987951==" List-Id: --===============8331804221342987951== Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Hey Rod, sorry that I did not reply earlier. On Thu, 2015-02-12 at 02:03 -0600, R. W. Rodolico wrote: > Who is actually managing the documentation? I have some articles written > (well, rough drafts). Is there one person who we should be talking to > about this? Nobody is, essentially. There are many people who write/edit an article every once in a while and there were some people who invested many hours like Erik. But there has never been a manager who has been managing people all the time. > Also, Michael talked about wanting a replacement for the software on the > documentation site. Does anyone have any ideas? I have a tech who is > also a web content person and I could donate some of her time to > transferring. She has already looked at the site and given a few > recommendations. Indeed I am not too pleases with Dokuwiki. It is not too bad but I am missing some functionality and a bit of performance. It is way better than all the alternatives that are out there. I just don't find it easy to use and I find the layout of the pages not too beautiful. Those are things that can be changed by using plugins but those are not always that well maintained. > Work appears to be slowing here a little, so maybe we could put a little > time in. That is great. We always need native speakers to proof-read some things. The main issue here is though that I need a commitment by more people to actually care about the documentation. Otherwise it won't work. It is not a task for just one or two people. It is something that needs to be done by many and there are many different tasks. Proof-reading texts that have been written by people who only speak English as a second language is just one small part of that. We also need good content. Comprehensive guides, good tutorials, in-depth explanations of things. -Michael > Rod >=20 > On 02/08/2015 07:05 AM, Michael Tremer wrote: > > Hello, > >=20 > > 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. > >=20 > > 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. > >=20 > > 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. > >=20 > > 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. > >=20 > > 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. > >=20 > > 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 > >=20 > > Then I created a section which just handles the ARM hardware: > >=20 > > http://wiki.ipfire.org/en/hardware/arm/start > >=20 > > 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. > >=20 > > 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. > >=20 > > 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. > >=20 > >=20 > > So to bring this all to a point: I am very much inclined to delete huge > > parts of the documentation. > >=20 > >=20 > > 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. > >=20 > > 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 > >=20 > > 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 > >=20 > > 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. > >=20 > > 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. > >=20 > > 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 > >=20 > >=20 > > 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. > >=20 > > 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. > >=20 > > 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. > >=20 > > 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). > >=20 > > 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. > >=20 > > 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. > >=20 > > Best, > > -Michael > >=20 > > _______________________________________________ > > Documentation mailing list > > Documentation(a)lists.ipfire.org > > http://lists.ipfire.org/mailman/listinfo/documentation > >=20 >=20 --===============8331804221342987951== Content-Type: application/pgp-signature Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="signature.asc" MIME-Version: 1.0 LS0tLS1CRUdJTiBQR1AgU0lHTkFUVVJFLS0tLS0KVmVyc2lvbjogR251UEcgdjIKCmlRSWNCQUFC Q2dBR0JRSlU0aitGQUFvSkVJQjU4UDl2a0FrSFRnc1AvMHVnNXNHNGYzTFdLSVVQVmVCWXZxdnYK c0lWMGl3VTVBbjlITTB5RHRiWG5OQ1hYMFJiQWNEZ3BXd2gwR01OTjI5R2V2WU9hdnNINjdTZlNu dTdkbTc0UApnVVpWbEtyU1dYWFdnZzd1VUJYSmNsSkZ1ekFrckFxNEphQ2dWUVViTXBkSzhpeG5Z dWxwM0k3anZLRko3M2p2CmN0cFNhQUxSV0ZoSHRnM3R0TnZqRWRqbTBOYzAzZnhBTU5hY2RoQkN2 T2JCaDd6UVNhRU9DUGFyWjFIUUYvRzYKRFJzNXFMSy9FMTlOeVpBbjhaWVVpS3ZiSEo2cS94eExT M2dEbEhGd0F6UFBkK1pJQmFvWlVReCtyWnlZU01yNApmNnNNWThZYW9ILzF5TlZwbjdJaklOVjNU aDhJOXlYbU5xdDl0L3VLeTV1MWpDZmNCWVR5bHZQWDlxTFRrQ3p2ClFCTWNWWEpFQ1JhTkxacURy RmtxRVlsSVd3dFU0L2FxNEhEU0gvMEs5M1E3eTh2cnVOVHo3SFVWRUp5SlBDVjgKZFd2T01QTVFj YnBHRlBDK00vTytBWlRvQmk4bHRucjBkaDY2ZUNqTXhvUEp6bjQ4Qk54aDlZZEc1eHBzQUI0bgpa dm1Oay9RYUJtY2pGSENFVkNHWVFhNEtyR3dEOFBQWFZQQmhHMkRzT25QbkdwNW00WnpuUEZ6WDdk UHpjcVlkCnE4dlBqN3dhSFJ3VDg3eCtmK0s3OEU5ZWpCWXAxTkRuMkhGTklQaVo0b0tYV01KbHlD VjFSc0oycXduczcrQSsKMXc3aHY5ZFdzMmh1cy9yVllQTnc1TVB6TFJYcHZhcWJxTlZIWkJaaUli WWRUak1TYlMwUWlmTTJPL2E2c1NregpOR1pTYmNkTFFhRGVyT2tVUFZOSQo9clk5egotLS0tLUVO RCBQR1AgU0lHTkFUVVJFLS0tLS0K --===============8331804221342987951==--