From mboxrd@z Thu Jan 1 00:00:00 1970 From: trymes@rymes.com To: documentation@lists.ipfire.org Subject: Re: Restructuring of the hardware section (i.e. removing duplicate/obsolete stuff) Date: Mon, 16 Feb 2015 17:21:56 -0500 Message-ID: In-Reply-To: <1424113537.17826.69.camel@ipfire.org> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="===============1433257220792354238==" List-Id: --===============1433257220792354238== Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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 detai= ls when the new firewall interface was introduced. Tom > On Feb 16, 2015, at 2:06 PM, Michael Tremer w= rote: >=20 > Hey Rod, >=20 > sorry that I did not reply earlier. >=20 >> 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? >=20 > 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. >=20 >> 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. >=20 > 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. >=20 >> Work appears to be slowing here a little, so maybe we could put a little >> time in. >=20 > 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. >=20 > -Michael >=20 >> 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 > 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: > 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 > To: "R. W. Rodolico" > 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)=20 > 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..." > List-Unsubscribe: , > > List-Archive: > List-Post: > List-Help: > List-Subscribe: , > > Content-Type: multipart/mixed; boundary=3D"=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D6022088350758620877=3D=3D" > Errors-To: documentation-bounces(a)lists.ipfire.org > Sender: "Documentation" >=20 >=20 > --=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D6022088350758620877=3D=3D > Content-Type: multipart/signed; micalg=3D"pgp-sha512"; > protocol=3D"application/pgp-signature"; boundary=3D"=3D-fkvUhoYEfOWxfQq7= rOr5" >=20 >=20 > --=3D-fkvUhoYEfOWxfQq7rOr5 > Content-Type: text/plain; charset=3D"UTF-8" > Content-Transfer-Encoding: quoted-printable >=20 > Hey Rod, >=20 > sorry that I did not reply earlier. >=20 >> 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? >=20 > 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. >=20 >> 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. >=20 > 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. >=20 >> Work appears to be slowing here a little, so maybe we could put a little >> time in. >=20 > 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. >=20 > -Michael >=20 >> Rod >> =3D20 >>> On 02/08/2015 07:05 AM, Michael Tremer wrote: >>> Hello, >>> =3D20 >>> 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. >>> =3D20 >>> 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. >>> =3D20 >>> 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 =3D > a >>> point where people are more confused by the documentation than it helps >>> them... we need to do something. >>> =3D20 >>> 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. >>> =3D20 >>> 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. >>> =3D20 >>> 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=3D > s >>> where made and what reasons are behind something. But having all that o=3D > 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=3D > s >>> the recommended hardware specification. All other information about tha=3D > t >>> can be found over here: http://wiki.ipfire.org/en/hardware/requirements >>> =3D20 >>> Then I created a section which just handles the ARM hardware: >>> =3D20 >>> http://wiki.ipfire.org/en/hardware/arm/start >>> =3D20 >>> 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=3D > 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. >>> =3D20 >>> 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=3D > 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. >>> =3D20 >>> Clean design and clear structure is hugely important. This wiki holds s=3D > 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=3D > e >>> with no background information, you are practically screwed. >>> =3D20 >>> =3D20 >>> So to bring this all to a point: I am very much inclined to delete huge >>> parts of the documentation. >>> =3D20 >>> =3D20 >>> I find it much better to have no information at all instead of providin=3D > g >>> the users with wrong information. Wrong could also mean just outdated o=3D > r >>> obsolete. >>> =3D20 >>> 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=3D > _4.1 >>> =3D20 >>> 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 >>> =3D20 >>> 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=3D > ? >>> I imagine this has happened because the author was unaware of the >>> existence of the one page. >>> =3D20 >>> 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. >>> =3D20 >>> 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=3D > t >>> imagine something else but deleting all of this. >>> http://wiki.ipfire.org/de/addons/virtualisation/howto/debian_als_dom0_x=3D > en >>> =3D20 >>> =3D20 >>> The other topic that is the missing translation is the firewall section=3D > . >>> 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. >>> =3D20 >>> It has been pointed out several times on the forums and many people mad=3D > e >>> promises to actually do something about it. No one ever did. It was not >>> even started. >>> =3D20 >>> 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=3D > 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. >>> =3D20 >>> 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). >>> =3D20 >>> 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. >>> =3D20 >>> 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. >>> =3D20 >>> Best, >>> -Michael >>> =3D20 >>> _______________________________________________ >>> Documentation mailing list >>> Documentation(a)lists.ipfire.org >>> http://lists.ipfire.org/mailman/listinfo/documentation >>> =3D20 >> =3D20 >=20 > --=3D-fkvUhoYEfOWxfQq7rOr5 > Content-Type: application/pgp-signature; name=3D"signature.asc" > Content-Description: This is a digitally signed message part > Content-Transfer-Encoding: 7bit >=20 > -----BEGIN PGP SIGNATURE----- > Version: GnuPG v2 >=20 > 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 > =3DrY9z > -----END PGP SIGNATURE----- >=20 > --=3D-fkvUhoYEfOWxfQq7rOr5-- >=20 >=20 > --=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D6022088350758620877=3D=3D > Content-Type: text/plain; charset=3D"us-ascii" > MIME-Version: 1.0 > Content-Transfer-Encoding: 7bit > Content-Disposition: inline >=20 > _______________________________________________ > Documentation mailing list > Documentation(a)lists.ipfire.org > http://lists.ipfire.org/mailman/listinfo/documentation >=20 > --=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D6022088350758620877=3D=3D-- >=20 --===============1433257220792354238==--