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

[trymes@rymes.com]

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

One thing that would be helpful is a clear policy on what to do with outdated information. I know that I personally struggled with how to handle old details when the new firewall interface was introduced.

Tom

> On Feb 16, 2015, at 2:06 PM, Michael Tremer <michael.tremer(a)ipfire.org> wrote:
> 
> 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
> X-CGP-ClamAV-Result: CLEAN
> X-VirusScanner: Niversoft's CGPClamav Helper v1.18.5 (ClamAV engine v0.98.5)
> X-PolluStop-Diagnostic:  (whitelisted by user)
> X-Orig-Return-Path: documentation-bounces(a)lists.ipfire.org
> X-Orig-Recipients: s9j0e1+WhT0mpneOkCtD0REdEqU2myLD
> X-AttachExt: asc
> X-PolluStop-Score: 0.00
> X-PolluStop: Scanned with Niversoft PolluStop v2.13.2
> Return-Path: <documentation-bounces(a)lists.ipfire.org>
> Received: from mail01.ipfire.org ([178.63.73.247] verified)
>  by rymes.com (CommuniGate Pro SMTP 5.4.11)
>  with ESMTPS id 9050334 for trymes(a)rymes.com; Mon, 16 Feb 2015 14:06:00 -0500
> Received: from hedwig.ipfire.org (localhost [IPv6:::1])
>    by mail01.ipfire.org (Postfix) with ESMTP id 59EB921C4;
>    Mon, 16 Feb 2015 20:05:43 +0100 (CET)
> Received: from rice-oxley.tremer.info (rice-oxley.tremer.info
> [IPv6:2001:470:1f09:1abc:beae:c5ff:fe04:be50])
> (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits))
> (No client certificate requested)
> by mail01.ipfire.org (Postfix) with ESMTPSA id 792C921A2;
> Mon, 16 Feb 2015 20:05:42 +0100 (CET)
> Message-ID: <1424113537.17826.69.camel(a)ipfire.org>
> Subject: Re: Restructuring of the hardware section (i.e. removing
> duplicate/obsolete stuff)
> From: Michael Tremer <michael.tremer(a)ipfire.org>
> To: "R. W. Rodolico" <rodo(a)dailydata.net>
> Date: Mon, 16 Feb 2015 20:05:37 +0100
> In-Reply-To: <54DC5E6F.9030803(a)dailydata.net>
> References: <1423400748.2329.43.camel(a)rice-oxley.tremer.info>
> <54DC5E6F.9030803(a)dailydata.net>
> Organization: IPFire.org
> X-Mailer: Evolution 3.12.10 (3.12.10-1.fc21) 
> Mime-Version: 1.0
> Cc: documentation(a)lists.ipfire.org
> X-BeenThere: documentation(a)lists.ipfire.org
> X-Mailman-Version: 2.1.18-1
> Precedence: list
> List-Id: "Discussions about the wiki,
> translations and stuff..." <documentation.lists.ipfire.org>
> List-Unsubscribe: <http://lists.ipfire.org/mailman/options/documentation>,
> <mailto:documentation-request(a)lists.ipfire.org?subject=unsubscribe>
> List-Archive: <http://lists.ipfire.org/pipermail/documentation/>
> List-Post: <mailto:documentation(a)lists.ipfire.org>
> List-Help: <mailto:documentation-request(a)lists.ipfire.org?subject=help>
> List-Subscribe: <http://lists.ipfire.org/mailman/listinfo/documentation>,
> <mailto:documentation-request(a)lists.ipfire.org?subject=subscribe>
> Content-Type: multipart/mixed; boundary="===============6022088350758620877=="
> Errors-To: documentation-bounces(a)lists.ipfire.org
> Sender: "Documentation" <documentation-bounces(a)lists.ipfire.org>
> 
> 
> --===============6022088350758620877==
> Content-Type: multipart/signed; micalg="pgp-sha512";
>    protocol="application/pgp-signature"; boundary="=-fkvUhoYEfOWxfQq7rOr5"
> 
> 
> --=-fkvUhoYEfOWxfQq7rOr5
> 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 decision=
> s
>>> where made and what reasons are behind something. But having all that o=
> n
>>> 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 show=
> s
>>> the recommended hardware specification. All other information about tha=
> t
>>> 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 th=
> e
>>> 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 th=
> e
>>> 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 s=
> o
>>> 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 tim=
> e
>>> 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 providin=
> g
>>> the users with wrong information. Wrong could also mean just outdated o=
> r
>>> 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 canno=
> t
>>> imagine something else but deleting all of this.
>>> http://wiki.ipfire.org/de/addons/virtualisation/howto/debian_als_dom0_x=
> en
>>> =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 mad=
> e
>>> 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 kee=
> p
>>> 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
> 
> --=-fkvUhoYEfOWxfQq7rOr5
> Content-Type: application/pgp-signature; name="signature.asc"
> Content-Description: This is a digitally signed message part
> Content-Transfer-Encoding: 7bit
> 
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2
> 
> iQIcBAABCgAGBQJU4j+FAAoJEIB58P9vkAkHTgsP/0ug5sG4f3LWKIUPVeBYvqvv
> sIV0iwU5An9HM0yDtbXnNCXX0RbAcDgpWwh0GMNN29GevYOavsH67SfSnu7dm74P
> gUZVlKrSWXXWgg7uUBXJclJFuzAkrAq4JaCgVQUbMpdK8ixnYulp3I7jvKFJ73jv
> ctpSaALRWFhHtg3ttNvjEdjm0Nc03fxAMNacdhBCvObBh7zQSaEOCParZ1HQF/G6
> DRs5qLK/E19NyZAn8ZYUiKvbHJ6q/xxLS3gDlHFwAzPPd+ZIBaoZUQx+rZyYSMr4
> f6sMY8YaoH/1yNVpn7IjINV3Th8I9yXmNqt9t/uKy5u1jCfcBYTylvPX9qLTkCzv
> QBMcVXJECRaNLZqDrFkqEYlIWwtU4/aq4HDSH/0K93Q7y8vruNTz7HUVEJyJPCV8
> dWvOMPMQcbpGFPC+M/O+AZToBi8ltnr0dh66eCjMxoPJzn48BNxh9YdG5xpsAB4n
> ZvmNk/QaBmcjFHCEVCGYQa4KrGwD8PPXVPBhG2DsOnPnGp5m4ZznPFzX7dPzcqYd
> q8vPj7waHRwT87x+f+K78E9ejBYp1NDn2HFNIPiZ4oKXWMJlyCV1RsJ2qwns7+A+
> 1w7hv9dWs2hus/rVYPNw5MPzLRXpvaqbqNVHZBZiIbYdTjMSbS0QifM2O/a6sSkz
> NGZSbcdLQaDerOkUPVNI
> =rY9z
> -----END PGP SIGNATURE-----
> 
> --=-fkvUhoYEfOWxfQq7rOr5--
> 
> 
> --===============6022088350758620877==
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
> 
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> http://lists.ipfire.org/mailman/listinfo/documentation
> 
> --===============6022088350758620877==--
>