Re: Restructuring of the hardware section (i.e. removing duplicate/obsolete stuff)

["R. W. Rodolico" <rodo@dailydata.net>]

[-- Attachment #1: Type: text/plain, Size: 7313 bytes --]

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