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? 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. Work appears to be slowing here a little, so maybe we could put a little time in. Rod On 02/08/2015 07:05 AM, Michael Tremer wrote: > 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 > -- "Rod" Rodolico Daily Data, Inc. POB 140465 Dallas TX 75214-0465 214.827.2170 http://www.dailydata.net