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

[Michael Tremer <michael.tremer@ipfire.org>]

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

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
> 
> 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
> > 
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]