Aw: IPFire Wiki Workflow

[Bernhard Bitsch <Bernhard.Bitsch@gmx.de>]

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

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 someone 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 good 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 originates 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" <michael.tremer(a)ipfire.org>
> An: documentation(a)lists.ipfire.org
> Betreff: IPFire Wiki Workflow
>
> Hello *,
> 
> 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.
> 
> 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.
> 
> 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.
> 
> So here is what I personally think the problems are:
> 
> 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 :)
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 
> 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:
> 
> a) We need to encourage more people to join the documentation team.
> People who actually do work on the team.
> 
> b) We need to find native speakers for the main languages which are
> English and German, to raise the quality of the language.
> 
> 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.
> 
> 
> I would like to see some things sorted that are essential for this to
> work:
> 
> * 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.
> 
> 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.
> 
> * 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.
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 
> 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.
> 
> 
> -Michael
> 
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> http://lists.ipfire.org/mailman/listinfo/documentation
>