From mboxrd@z Thu Jan 1 00:00:00 1970 From: Bernhard Bitsch To: documentation@lists.ipfire.org Subject: Aw: IPFire Wiki Workflow Date: Wed, 10 Jul 2013 23:02:42 +0200 Message-ID: In-Reply-To: <1373449618.15464.139.camel@rice-oxley.tremer.info> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="===============4155904566888620651==" List-Id: --===============4155904566888620651== Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Hello Michael, I agree in all points with you ( did you expectthis ;) ). At the moment the Wiki is in many places just a collection of articles someon= e thought of it would be interesting for the community. This results in a lack of completeness and actuality. Therefore your suggestion about a step by step revision of the chapters is go= od way to achieve higher quality. Let me add my favourite suggestion: An article should be written by a native = speaker, or the "final" version must be corrected and revised by such a team = member. The main reason is, usually the most exact description of a fact can be done = in the language you have the most experience, the mother language. This is an= experience from many years of work in software development. This means that an article written by someone with knowledge of a topic origi= nates in her/his native language. And should be translated by the translation= team. I realise, that this results in scattered Wiki in the first phase. But= for clearness we should dare this. I hope, I was successful in expressing my thoughts in English. ;) Bernhard > Gesendet: Mittwoch, 10. Juli 2013 um 11:46 Uhr > Von: "Michael Tremer" > An: documentation(a)lists.ipfire.org > Betreff: IPFire Wiki Workflow > > Hello *, >=20 > as mentioned before I want to discuss the situation of the documentation > in the IPFire project. This is a hard topic and I am sure we won't find > a solution that will fix all the problems we are experiencing now in a > swift, but at least I would like to find out what we are doing wrong and > what we can do about it. >=20 > Disclaimer: The documentation on the IPFire wiki is not all in a bad > quality. There are some parts which are well written but there are other > parts which are not. I will be mostly talking about the bad parts, here. >=20 > In the last couple of weeks, some people came to me and complained about > the wiki. That's what made me think again about the problem. We all know > that this has been a problem for years, but as the project is growing > bigger and bigger, there are more people trying to find information on > the wiki, but they can't. >=20 > So here is what I personally think the problems are: >=20 > 1) There is an answer to almost every question on the wiki, but nobody > can find it. The presentation of the information and the structure is > not very good on some pages. Some are too long, some things are too > short. Some pages are not even linked and only accessible via the search > - we all know how much people like the search :) >=20 > People who are joining the project and are installing IPFire for the > first time are basically on their own, because reading the installation > guide takes hours and states a lot of obvious things. What to do after > that (like configuring your DSL connection) can not be found anywhere. >=20 > 2) The different translations are in very poor quality. Some parts of > English and German sounds as if they have been translated by Babelfish. > We are lacking native speakers for everything else than German, and even > there, we need to fix a lot of grammar, wording, orthography and more. >=20 > 3) Problems 1) and 2) essentially boil down to: We don't have enough man > power. The list of people which are in the documentation team is long, > but if you kick out all the people who are inactive, you are left over > with only a few. >=20 > Erik is the current wiki coordinator who manages the documentation team, > but there is really nothing to manage at the moment. He is doing a lot > of work, but maintaining the entire wiki by only one person is not > working. Nobody can do that. >=20 >=20 > I don't have THE solution to fix all the problems, but I have a few > suggestions to make and I would like to hear your opinions about that: >=20 > a) We need to encourage more people to join the documentation team. > People who actually do work on the team. >=20 > b) We need to find native speakers for the main languages which are > English and German, to raise the quality of the language. >=20 > c) We need a better structure for beginners, because that's the group of > people the documentation is meant for. We need to cover things like the > installation and initial setup much better, shorter and sweeter, because > setting up IPFire is not a big deal, but there should documentation that > tells the user what to do next. >=20 >=20 > I would like to see some things sorted that are essential for this to > work: >=20 > * There must be guide that tells people how to contribute to the > documentation. There need to be styling and language guidelines, which > have to be written. Those will help people to get started writing > documentation and tells them how to contribute in the right way. >=20 > Lots don't know how to edit the wiki. Others don't have the confidence > to change anything and are afraid that they will mess things up. We need > to tell them that they are not alone in this and that even small > improvements are very important - and easy to make as well. >=20 > * After that I would like to start rewriting sections one after an > other. Maybe we can create a workflow that is roughly like this: > i) Grab some topic and discuss what the problems are and what > needs to be improved. > ii) A one week(?) phase were a team of authors is (re-)writing. > iii) A one week(?) phase for QA, reviewing what has been done. > iv) After that team of authors starts at i) with a new section. > The translation teams translate the work into their respective > languages. >=20 > The coordinator's task will be (despite writing and translating) to > check that process is followed and he will also check if the result > complies to the guidelines. >=20 > A workflow like this has a lot of advantages, because it is highly > modular. If there is more time needed for writing it can easily be > extended. Lot's of people can work on it at the same time and they will > check each others work for mistakes which results in a higher quality. > You don't have too much on your plate and won't lose focus. Everybody > knows what the team is working on and can join. >=20 > Working on other sections during phase ii) should not be strictly > forbidden but discouraged so that there is not too much to do at the > same time, but it should be allowed to make trivial changes and so on. >=20 >=20 > So that's my idea about how this could/should work. Please post your > opinions and your ideas at well. Share what you think the major problems > are, so that we can work them out. >=20 >=20 > -Michael >=20 > _______________________________________________ > Documentation mailing list > Documentation(a)lists.ipfire.org > http://lists.ipfire.org/mailman/listinfo/documentation >=20 --===============4155904566888620651==--