IPFire Wiki Workflow

IPFire Wiki Workflow

[Michael Tremer]

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

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

Aw: IPFire Wiki Workflow

[Bernhard Bitsch]

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

Re: Aw: IPFire Wiki Workflow

[Michael Tremer]

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

On Wed, 2013-07-10 at 23:02 +0200, Bernhard Bitsch wrote:
> 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.

I was not only aiming at rewriting one section after an other, but
rather building a workflow where all people have got a certain task and
produce some sophisticated output.

Again, not everything on the wiki is bad.

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

We don't have enough native speakers for all the languages at the
moment. It's one of the problems we have to fix in the beginning.

As a lot of the work on the wiki is translating texts from one language
into an other, most of the team members need to speak more than one
language.

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

We are all very (maybe most) eloquent in our mother language, but we
also need a common denominator which is English. In our current
situation we don't have any experts who speak for example French.
Therefore nobody is writing original documentation in French. But we do
have people who are able to translate content from English to French and
that helps us to provide documentation to people who only speak French.

I would suggest to make a simple rule, which has to be strictly
followed. It would solve the problem that the different translations are
drifting apart: Every change has to be done in English first. No matter
if it is just adding a tiny piece of information or writing an entire
new page.
By doing that, the translators always have a valid and up to date
reference which is English, which most people speak as a second
language.

> I hope, I was successful in expressing my thoughts in English. ;)

Yes, you were. See? It's already working.

-Michael

Re: IPFire Wiki Workflow

[R. W. Rodolico]

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

Hey, I'm one of those people in Section 3 that Michael talks about. I'm
"on" the documentation team, but really don't do much.

I think, for me at least, the problem is two-fold. First, I'm confused
as to what I should do. Second, I'm unsure of how I do it.

For me, personally, if I had a small, defined task that I was to do, and
knew who it was that was supposed to approve what I am supposed to do,
you might get a little work out of me.

I also agree it is the organization of the the wiki that makes it
difficult. The information is there, and a lot of it is very good. But,
it was only on my 3rd or 4th install that I realized it even existed.

I, like everyone, have other things that I must do to pay the rent and
such. However, I love IPFire, and use it quite a bit. I want to give
back. The only thing I've done so far is to make a few minor changes in
one page, because someone mentioned it needed to be done. I saw other
things that needed to be changed, but did not want to "step on anyone's
toes" (American for cause bad feelings by changing something someone
else did, and them feeling like I was saying it wasn't good enough).

I like most of what Michael said. I think that under these
circumstances, I might actually be able to be less of a leech and
actually contribute.

I would recommend that the task be small and well defined, in both scope
and date when the results were expected. And, that would be a total pain
for Erik. However, I think that having a task that could be completed in
a couple of hours, and was due within a week, would result in more being
done on this.

My opinion. I would like to help, I just am not sure what to do to help.

Rod

On 07/10/2013 04:46 AM, Michael Tremer wrote:
> 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
> 

-- 
R. W. "Rod" Rodolico
Daily Data, Inc.
POB 140465
Dallas TX 75214-0465
http://www.dailydata.net
214.827.2170


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: rodo.vcf --]
[-- Type: text/x-vcard, Size: 233 bytes --]

begin:vcard
fn:R. W. Rodolico
n:Rodolico;R. W.
org:Daily Data, Inc.
adr:;;POB 140465;Dallas;TX;75214-0465;US
email;internet:rodo@dailydata.net
title:President
tel;work:214.827.2170
url:http://www.dailydata.net
version:2.1
end:vcard

Re: IPFire Wiki Workflow

[Michael Tremer]

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

Thank you for your feedback, Rod.

On Thu, 2013-07-11 at 02:28 -0500, R. W. Rodolico wrote:
> Hey, I'm one of those people in Section 3 that Michael talks about. I'm
> "on" the documentation team, but really don't do much.

I wasn't aware that you were on the team.

> I think, for me at least, the problem is two-fold. First, I'm confused
> as to what I should do. Second, I'm unsure of how I do it.
> 
> For me, personally, if I had a small, defined task that I was to do, and
> knew who it was that was supposed to approve what I am supposed to do,
> you might get a little work out of me.
> 
> I also agree it is the organization of the the wiki that makes it
> difficult. The information is there, and a lot of it is very good. But,
> it was only on my 3rd or 4th install that I realized it even existed.

If I would need to bring all this to terms I would call it "awareness".

Everyone (literally - people on and off the documentation team) should
be aware of what is been done at the moment. What has been done recently
and what will be done in the future. On top of that it would be good to
know who is doing what, so that I can contact that person if I have got
something to contribute or what ever...

> I, like everyone, have other things that I must do to pay the rent and
> such. However, I love IPFire, and use it quite a bit. I want to give
> back. The only thing I've done so far is to make a few minor changes in
> one page, because someone mentioned it needed to be done. I saw other
> things that needed to be changed, but did not want to "step on anyone's
> toes" (American for cause bad feelings by changing something someone
> else did, and them feeling like I was saying it wasn't good enough).
> 
> I like most of what Michael said. I think that under these
> circumstances, I might actually be able to be less of a leech and
> actually contribute.
> 
> I would recommend that the task be small and well defined, in both scope
> and date when the results were expected. And, that would be a total pain
> for Erik. However, I think that having a task that could be completed in
> a couple of hours, and was due within a week, would result in more being
> done on this.

The due dates. This is a huge concern for me and we also have this issue
in the development team. We all do not work full time on the project, so
the project has a bit of a lower priority to us than paying rent and
things like that.

Sometimes there is a lot of spare time that can be invested into the
project and sometimes there is not. It varies quite a bit and planning
with that is hard.

If someone has a solution how to define due dates in a way that we don't
set them too far in the future and everybody is idle and that we don't
set them too early because there may be other things that are more
important and need to be done first.

A strict two week schedule may work for some tasks, but not for others.
Can we add something like a "fast sprint" of only one week? Should we
set no due dates at all?

> My opinion. I would like to help, I just am not sure what to do to help.

We will figure that out :)

-Michael

Re: IPFire Wiki Workflow

[R. W. Rodolico]

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



On 07/11/2013 05:01 AM, Michael Tremer wrote:
> Thank you for your feedback, Rod.
> 
> On Thu, 2013-07-11 at 02:28 -0500, R. W. Rodolico wrote:
>> Hey, I'm one of those people in Section 3 that Michael talks about. I'm
>> "on" the documentation team, but really don't do much.
> 
> I wasn't aware that you were on the team.

"On the team" may be over stating it. One time, several months ago,
someone mentioned on this list that something needed to be changed in
the wiki; updates by a native English speaker. I looked at it,
volunteered to do it and did it. That is the one and only time I've done
anything on the documentation.

That incident is what led to my observations. I wanted to do something,
but was very unsure of the scope of changes: make simple
grammatical/spelling corrections or rewrite the entire thing. I also
remember it was somewhat interesting figuring out the markup language.

> 
>> I think, for me at least, the problem is two-fold. First, I'm confused
>> as to what I should do. Second, I'm unsure of how I do it.
>>
>> For me, personally, if I had a small, defined task that I was to do, and
>> knew who it was that was supposed to approve what I am supposed to do,
>> you might get a little work out of me.
>>
>> I also agree it is the organization of the the wiki that makes it
>> difficult. The information is there, and a lot of it is very good. But,
>> it was only on my 3rd or 4th install that I realized it even existed.
> 
> If I would need to bring all this to terms I would call it "awareness".
> 
> Everyone (literally - people on and off the documentation team) should
> be aware of what is been done at the moment. What has been done recently
> and what will be done in the future. On top of that it would be good to
> know who is doing what, so that I can contact that person if I have got
> something to contribute or what ever...
> 
>> I, like everyone, have other things that I must do to pay the rent and
>> such. However, I love IPFire, and use it quite a bit. I want to give
>> back. The only thing I've done so far is to make a few minor changes in
>> one page, because someone mentioned it needed to be done. I saw other
>> things that needed to be changed, but did not want to "step on anyone's
>> toes" (American for cause bad feelings by changing something someone
>> else did, and them feeling like I was saying it wasn't good enough).
>>
>> I like most of what Michael said. I think that under these
>> circumstances, I might actually be able to be less of a leech and
>> actually contribute.
>>
>> I would recommend that the task be small and well defined, in both scope
>> and date when the results were expected. And, that would be a total pain
>> for Erik. However, I think that having a task that could be completed in
>> a couple of hours, and was due within a week, would result in more being
>> done on this.
> 
> The due dates. This is a huge concern for me and we also have this issue
> in the development team. We all do not work full time on the project, so
> the project has a bit of a lower priority to us than paying rent and
> things like that.
> 
> Sometimes there is a lot of spare time that can be invested into the
> project and sometimes there is not. It varies quite a bit and planning
> with that is hard.
> 
> If someone has a solution how to define due dates in a way that we don't
> set them too far in the future and everybody is idle and that we don't
> set them too early because there may be other things that are more
> important and need to be done first.
> 
> A strict two week schedule may work for some tasks, but not for others.
> Can we add something like a "fast sprint" of only one week? Should we
> set no due dates at all?

I run a small computer consulting business where I have a couple of
tech's working for me, either as consultants or employees. Some of our
tasks take longer, some are quick.

In some ways it is similar to IPFire. I am really the only full time
employee; everyone else works either as needed/as available or part
time. So, I have to keep in mind the constraints on their time (they all
have other jobs). However, they do work for pay, so that is a difference.

We use RequestTracker (http://bestpractical.com/rt/), and no, I am not
suggesting that for IPFire. I'm simply pointing out how we do things.

When a task comes in, we either leave it unassigned in the general
queue, or I assign it to someone. Theoretically, the other techs also
look at the unassigned tickets and, if it is in their skill set, they
take the task (actually, they are getting better at it now).

However, there is a nice, simple list everyone in the organization can
look at, of tasks that are to be done by them. They are arraigned by
priority, and there is a column showing how long it has been open, and
also how long it has been since they did anything. Tech's log in, look
at their tasks, then work on one or more of them. When the task is
complete, they set the status to "resolved" and it is removed from
active tickets, but stored in the system for reference in the future.

Again, I'm not trying to get IPFire to move to Request Tracker. It took
me a while to install and configure, and there are other solutions that
may work better for this project (bugzilla is one). However, I do see
some advantages to a system like this. Everyone sees their tasks (and
the tasks assigned to others). When tasks are completed, they are
retained so we can look at historical data (for clients who have similar
problems), etc...

A quick scan of the Request Tracker wikipedia entry showed lists of
about two dozen similar solutions.
https://en.wikipedia.org/wiki/Comparison_of_issue_tracking_systems shows
a comparison and https://en.wikipedia.org/wiki/Request_Tracker is the
Request Tracker page.

If someone wants to see what I'm talking about, I'd be happy to give you
a temporary login to it, or maybe build a separate instance you could
look at and play with.

> 
>> My opinion. I would like to help, I just am not sure what to do to help.
> 
> We will figure that out :)
> 
> -Michael
> 

-- 
R. W. "Rod" Rodolico
Daily Data, Inc.
POB 140465
Dallas TX 75214-0465
http://www.dailydata.net
214.827.2170


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: rodo.vcf --]
[-- Type: text/x-vcard, Size: 245 bytes --]

begin:vcard
fn:R. W. Rodolico
n:Rodolico;R. W.
org:Daily Data, Inc.
adr:;;POB 140465;Dallas;TX;75214-0465;US
email;internet:rodo@dailydata.net
title:President
tel;work:214.827.2170
url:http://www.dailydata.net
version:2.1
end:vcard

Re: IPFire Wiki Workflow

[Erik K.]

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

Hi all,
regarding to the ideas causing a better overview of the wiki content, i have tried a more compressed layout of the configuration wiki. The actual (official) look of this section can be found in here --> http://wiki.ipfire.org/en/configuration/start . 
The new one is very unready and only a first try, but it should show an idea how it could be better overviewed. 
In here --> http://wiki.ipfire.org/en/configuration/start you belong to the new structure.
Until now there is no content behind the structure but this should be done fast by a copy and paste of the old content. <-- Better to check out some sections before. Another possibility in this kind of structure can be to work more precised in themes with e.g. 5-10 different sections not as before with 40-50 (example in here --> http://wiki.ipfire.org/en/configuration/start ).

A statement to the wiki workflow:
In the last months, mostly work was done in particular articles of the wiki, also to clean up the code cause a lot of plugins was replaced, so the general structure wasn´t touched but becomes more and more informations. I think most important is for the first
	* Find out a new structure which can be better overviewed (configuration and installation, ???).
	* Go for a checkout of the basic system articles (without addons) and find out the worse sections to make them better and clearer.
	* If old articles will be revised, the explained functions should also be tested.
	* Documentation should be a part of the development of software (and if it is only a short developer hand out) so a possible documentation "team" have it easier.

Also to overview the actual changes in the wiki needs to be checked. In here --> http://wiki.ipfire.org/start?do=recent a done list can be overviewed. If there was a change in german, it might be great to find it also in the english wiki. As more people looks in there as better it is.

The native speakers: It is very important to have some people especial in english (american/english). The best might be that some people are native in two languages german/english otherwise we have the same condition than before. I tried always my best as an native german speaker to translate the wikis into english, but thats not enough for a good feeling by reading. So i tried always to send some messages over the docu mailinglist with the please that someone can go for corrections (also in german). Sometimes this kind of workflow did it very good (thanks again Rod by the way ;-), but sometimes (especially in the last past months) there was no response. As time goes by the wiki articles leaves the memory that there was something to do and they where forgotten. So it is maybe an idea to mark those articles as "uncheck, everybody is invited to go for a revise" or something.

So for the first some ideas from me.


Greetings 


Erik

Re: IPFire Wiki Workflow

[Erik K.]

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

Sorry wrong link for the new structure, this one is it --> http://wiki.ipfire.org/nonpublic/de/configuration/start

Am 11.07.2013 um 19:30 schrieb Erik K.:

> Hi all,
> regarding to the ideas causing a better overview of the wiki content, i have tried a more compressed layout of the configuration wiki. The actual (official) look of this section can be found in here -->http://wiki.ipfire.org/en/configuration/start . 
> The new one is very unready and only a first try, but it should show an idea how it could be better overviewed. 
> In here --> http://wiki.ipfire.org/en/configuration/start you belong to the new structure.
> Until now there is no content behind the structure but this should be done fast by a copy and paste of the old content. <-- Better to check out some sections before. Another possibility in this kind of structure can be to work more precised in themes with e.g. 5-10 different sections not as before with 40-50 (example in here --> http://wiki.ipfire.org/en/configuration/start ).
> 
> A statement to the wiki workflow:
> In the last months, mostly work was done in particular articles of the wiki, also to clean up the code cause a lot of plugins was replaced, so the general structure wasn´t touched but becomes more and more informations. I think most important is for the first
> 	* Find out a new structure which can be better overviewed (configuration and installation, ???).
> 	* Go for a checkout of the basic system articles (without addons) and find out the worse sections to make them better and clearer.
> 	* If old articles will be revised, the explained functions should also be tested.
> 	* Documentation should be a part of the development of software (and if it is only a short developer hand out) so a possible documentation "team" have it easier.
> 
> Also to overview the actual changes in the wiki needs to be checked. In here --> http://wiki.ipfire.org/start?do=recent a done list can be overviewed. If there was a change in german, it might be great to find it also in the english wiki. As more people looks in there as better it is.
> 
> The native speakers: It is very important to have some people especial in english (american/english). The best might be that some people are native in two languages german/english otherwise we have the same condition than before. I tried always my best as an native german speaker to translate the wikis into english, but thats not enough for a good feeling by reading. So i tried always to send some messages over the docu mailinglist with the please that someone can go for corrections (also in german). Sometimes this kind of workflow did it very good (thanks again Rod by the way ;-), but sometimes (especially in the last past months) there was no response. As time goes by the wiki articles leaves the memory that there was something to do and they where forgotten. So it is maybe an idea to mark those articles as "uncheck, everybody is invited to go for a revise" or something.
> 
> So for the first some ideas from me.
> 
> 
> Greetings 
> 
> 
> Erik

Re: IPFire Wiki Workflow

[Michael Tremer]

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

Great thoughts, but let's bring down the pace a little bit before we
start talking about the actual content that needs to be reviewed and
possibly (re-written).

I am still aiming for defining a workflow in this discussion that should
be followed under all circumstance, because I think this is what is most
important on a team, that we are all on the "same page" (almost
literally in this context).

Central questions are:

* How do we attract authors? (People who write content)
* How do we attract translators? (People who translate the content from
English into their respective languages)
* How do we decide what to work on? When? For how long?

The has to be a "team", otherwise we don't need to think about the
content.

On your note about that development has to be involved in this as well:
Agreed and I already talked to Arne and Stevee how we can do that in the
least time consuming way, because we also don't have much time and loads
of things to work on.
Writing articles in more than one language is an absolute no-go. We will
leave it at English and write down the most important things one needs
to know about a certain add-on or what ever. Adding screenshots, doing
the translations and getting the article into a round shape should be
the task of the translation team. Could you guys agree on that?

I also think that developers are not the best people to write end-user
documentation. It is getting to complex and not suitable for beginners
any way.

-Michael

On Thu, 2013-07-11 at 19:30 +0200, Erik K. wrote:
> Hi all,
> regarding to the ideas causing a better overview of the wiki content, i have tried a more compressed layout of the configuration wiki. The actual (official) look of this section can be found in here --> http://wiki.ipfire.org/en/configuration/start . 
> The new one is very unready and only a first try, but it should show an idea how it could be better overviewed. 
> In here --> http://wiki.ipfire.org/en/configuration/start you belong to the new structure.
> Until now there is no content behind the structure but this should be done fast by a copy and paste of the old content. <-- Better to check out some sections before. Another possibility in this kind of structure can be to work more precised in themes with e.g. 5-10 different sections not as before with 40-50 (example in here --> http://wiki.ipfire.org/en/configuration/start ).
> 
> A statement to the wiki workflow:
> In the last months, mostly work was done in particular articles of the wiki, also to clean up the code cause a lot of plugins was replaced, so the general structure wasn´t touched but becomes more and more informations. I think most important is for the first
> 	* Find out a new structure which can be better overviewed (configuration and installation, ???).
> 	* Go for a checkout of the basic system articles (without addons) and find out the worse sections to make them better and clearer.
> 	* If old articles will be revised, the explained functions should also be tested.
> 	* Documentation should be a part of the development of software (and if it is only a short developer hand out) so a possible documentation "team" have it easier.
> 
> Also to overview the actual changes in the wiki needs to be checked. In here --> http://wiki.ipfire.org/start?do=recent a done list can be overviewed. If there was a change in german, it might be great to find it also in the english wiki. As more people looks in there as better it is.
> 
> The native speakers: It is very important to have some people especial in english (american/english). The best might be that some people are native in two languages german/english otherwise we have the same condition than before. I tried always my best as an native german speaker to translate the wikis into english, but thats not enough for a good feeling by reading. So i tried always to send some messages over the docu mailinglist with the please that someone can go for corrections (also in german). Sometimes this kind of workflow did it very good (thanks again Rod by the way ;-), but sometimes (especially in the last past months) there was no response. As time goes by the wiki articles leaves the memory that there was something to do and they where forgotten. So it is maybe an idea to mark those articles as "uncheck, everybody is invited to go for a revise" or something.
> 
> So for the first some ideas from me.
> 
> 
> Greetings 
> 
> 
> Erik
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> http://lists.ipfire.org/mailman/listinfo/documentation

Aw: Re: IPFire Wiki Workflow

[Bernhard Bitsch]

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


> On your note about that development has to be involved in this as well:
> Agreed and I already talked to Arne and Stevee how we can do that in the
> least time consuming way, because we also don't have much time and loads
> of things to work on.
Sorry, documentation is not an addon, but a essential part of development.

> Writing articles in more than one language is an absolute no-go.
Agreed. ;)

> We will leave it at English and write down the most important things one needs
> to know about a certain add-on or what ever.
Most developpers are native german speakers. Why not using german?
 
> I also think that developers are not the best people to write end-user
> documentation. It is getting to complex and not suitable for beginners
> any way.
Also agreed. But without a basic documentation a non-developper can't write a end user doc.
The devs mainly know about the internals. A non-dev can only study the behaviour or ask the devs.

- Bernhard

Re: Aw: Re: IPFire Wiki Workflow

[Michael Tremer]

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

On Fri, 2013-07-12 at 14:10 +0200, Bernhard Bitsch wrote:
> > On your note about that development has to be involved in this as well:
> > Agreed and I already talked to Arne and Stevee how we can do that in the
> > least time consuming way, because we also don't have much time and loads
> > of things to work on.
> Sorry, documentation is not an addon, but a essential part of development.

Nobody said that. But we don't have not very much man power in
development and so there is nothing left to write end-user
documentation.

> > Writing articles in more than one language is an absolute no-go.
> Agreed. ;)
> 
> > We will leave it at English and write down the most important things one needs
> > to know about a certain add-on or what ever.
> Most developpers are native german speakers. Why not using german?

Because there are not enough people around who speak German and an other
language to translate the content to. Just take it as it is: German is
not the first language of this wiki and never will be.

The reasons for that are obvious and I have explained them to you more
than once. So stop ranting about this on every occasion.

> > I also think that developers are not the best people to write end-user
> > documentation. It is getting to complex and not suitable for beginners
> > any way.
> Also agreed. But without a basic documentation a non-developper can't write a end user doc.
> The devs mainly know about the internals. A non-dev can only study the behaviour or ask the devs.

What do you need to know about the "internals". Not very much.
Development documentation and end-user documentation are two completely
different things and we should not confuse those two.

As pointed out in my other email, I don't want to talk about development
documentation here and I also don't want to talk about how the
developers interact with the documentation team. There will be an
information exchange, but I am not sure in what form at the moment and
we will need to figure that out in the development team first.

-Michael

Re: Aw: Re: IPFire Wiki Workflow

[R. W. Rodolico]

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



On 07/12/2013 07:10 AM, Bernhard Bitsch wrote:
> 
>> On your note about that development has to be involved in this as well:
>> Agreed and I already talked to Arne and Stevee how we can do that in the
>> least time consuming way, because we also don't have much time and loads
>> of things to work on.
> Sorry, documentation is not an addon, but a essential part of development.
> 
>> Writing articles in more than one language is an absolute no-go.
> Agreed. ;)
> 
>> We will leave it at English and write down the most important things one needs
>> to know about a certain add-on or what ever.
> Most developpers are native german speakers. Why not using german?

I vote for English, and not because I am a native speaker, but for the
assumption that more people use it as a second language than German. I
speak English and (very poor) Spanish. I have Russian, Filipino, German
and Spanish native speakers I correspond with regularly because they
learned English in school.

I can't speak for other countries, but in the US, most of the
multilingual learn Spanish, French, German, Russian, Mandarin and
Japanese. However, I believe most of the multilingual in other countries
learn English as their second language, then go on to other languages
after that. I am speaking from my own experience, however, so I may be
wrong on this.

>  
>> I also think that developers are not the best people to write end-user
>> documentation. It is getting to complex and not suitable for beginners
>> any way.
> Also agreed. But without a basic documentation a non-developper can't write a end user doc.
> The devs mainly know about the internals. A non-dev can only study the behaviour or ask the devs.
> 
> - Bernhard
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> http://lists.ipfire.org/mailman/listinfo/documentation
> 

-- 
R. W. "Rod" Rodolico
Daily Data, Inc.
POB 140465
Dallas TX 75214-0465
http://www.dailydata.net
214.827.2170


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: rodo.vcf --]
[-- Type: text/x-vcard, Size: 233 bytes --]

begin:vcard
fn:R. W. Rodolico
n:Rodolico;R. W.
org:Daily Data, Inc.
adr:;;POB 140465;Dallas;TX;75214-0465;US
email;internet:rodo@dailydata.net
title:President
tel;work:214.827.2170
url:http://www.dailydata.net
version:2.1
end:vcard

Re: IPFire Wiki Workflow

[Michael Tremer]

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

Hello,

one very important note, which apparently didn't come across:

My intention was, that there is only one "instance" of the workflow
running at the same time and not an extra iteration per page.

If you do an different things at different times, it will get hard to
keep track about what is currently done. That doesn't make any sense to
me.


On Wed, 2013-07-31 at 20:51 +0200, Erik K. wrote:
> > 
> >> - In point (B) shouldn´t be not also the german translations in there as a point (2) ?
> > 
> > No,  the idea is to write the content in English first. And after that
> > has been finished and been reviewed (C), we start translating.
> > 
> > I guess the translation teams will organize themselves in a way they
> > like. They are usually much smaller and do not need a lot of
> > coordination.
> > 
> > The workflow implies one very import thing: English first.
> > No content is ever created first in any other language than English.
> > After it has been reviewed, we start translations into second languages.
> 
> I think also, for the first the docu team is very small and for sure as time goes by, there will be a good way how to do it. So should the workflow be adjusted in point (D) with the german translation ? I think it is a good idea if we bring on the german translation also as a fix point, otherwise we can run in a reversed situation to now that the english parts will grow and the german part will hobbles afterwards. Or do we abolish the german wiki ?

As the very last note on languages: Writing documentation does not need
to care about other languages (!= English). So details about the
translation process do not need to be included in the documentation
workflow.

Translations come AFTER content has been written. That's the only
relation between writing documentation and translating documentation.

We do not drop the German wiki at any point if there are enough people
to contribute to it. That's the same with other languages. If someone
wants to do it, that's fine and we will support that.

> 
> > 
> >> - The testing of the written articles should be mentioned i think, cause it is not enough to understand what this software should do, the software needs to be tested in every single function so a quality management will be done too.
> > 
> > This should be part of the review.
> 
> O.K. so part (C), should we adjust it in the workflow ?

Please add that note to the explanation below.

> >> A question: Should i start as a coordinator to list some important topics ? Or do we need a little longer ?
> > 
> > This list should be open (as basically everything). I suppose it's best
> > to create an extra wiki page for that and write down what needs to be
> > done. In addition to that we should set a priority and write down notes
> > about what particularly needs to be improved on an article.
> 
> Something like this --> http://wiki.ipfire.org/de/todo ? Please extend if you have some ideas.

This is in the wrong language are, obviously.

In general, there should be two kinds of lists:
1) A list of which articles is currently worked on.
2) A list of items that is to be scheduled for next iteration.

Again: Don't care about German at this point. Don't add percentages,
because how do you calculate these?

Michael

Re: IPFire Wiki Workflow

[Michael Tremer]

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

Hey Erik,

great that you are back from traveling and that we can finally go on
with this one.

On Sat, 2013-07-27 at 18:00 +0200, Erik K. wrote:
> Hi Michael,
> so for the first i think your workflow looks pretty good, but i have some possible enhancements how to extend this workflow. 
> - The developers and their new developments should become also a part of Point (A) i think. Stevee shows a good way how a short developer hand out could looks like, take a look in here --> http://wiki.ipfire.org/en/configuration/network/dnsforward . So the coordinator needs to know about this changes too that he can define a priority in the topics.

The idea is right, that developers should create a small page with the
most essential information about a new feature, but I don't see how this
is involved in the workflow of the documentation team.

I think we should work on an extra development workflow and at the end
of that, it should be mandatory to create that page and send the
information about the existence of that to the wiki coordinator.

Basically, this happens independently from the documentation workflow.

> - In point (B) shouldn´t be not also the german translations in there as a point (2) ?

No,  the idea is to write the content in English first. And after that
has been finished and been reviewed (C), we start translating.

I guess the translation teams will organize themselves in a way they
like. They are usually much smaller and do not need a lot of
coordination.

The workflow implies one very import thing: English first.
No content is ever created first in any other language than English.
After it has been reviewed, we start translations into second languages.

> - The testing of the written articles should be mentioned i think, cause it is not enough to understand what this software should do, the software needs to be tested in every single function so a quality management will be done too.

This should be part of the review.

> 	--> I think a new guideline for new and old wikis should be to explain every function which can be seen on the WUI, this means especially the core development or addons where a GUI was also developed by the IPFire team..
> 	--> Addons with foreign documentations can also become a short docu, but they should be linked to the external wiki/docu. This should also be a part of a guideline too.

To give a short answer on this: We should not copy content or write
articles about things that are not part of our business. Just link to
it.

We should discuss some general styling guidelines after we have proved
that the desired workflow is actually working.

> A question: Should i start as a coordinator to list some important topics ? Or do we need a little longer ?

This list should be open (as basically everything). I suppose it's best
to create an extra wiki page for that and write down what needs to be
done. In addition to that we should set a priority and write down notes
about what particularly needs to be improved on an article.

Here are two things that are due until the release of the next core
update, which will be roughly 2 weeks. Possibly less.

 * Wireless Client on RED
 * DNS Forwarding GUI

> 
> ------------------------
> 
> A guideline of how to structure the content and the layout of the wiki might be important for the workflow i think. This should prevent that people doing very different stuff if they work together in the same sections. So i have found until now 2 different guidelines for the IPFire wiki. 
> 
> - http://wiki.ipfire.org/nonpublic/en/guidelines
> - http://wiki.ipfire.org/en/edit
> 
> So some questions to you all regarding to this theme: 
> - What kind of layout and content structure we should use ? 
> - What things are missing in those guidelines ?
> - To make one good guideline please give some suggestions to them.

Let's discuss that later and let's focus on the content right now.

Best,
-Michael

Re: IPFire Wiki Workflow

[Erik K.]

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

Have found another possible wiki guideline list :-)


http://wiki.ipfire.org/en/wiki/syntax

Am 27.07.2013 um 18:00 schrieb Erik K.:

> Hi Michael,
> so for the first i think your workflow looks pretty good, but i have some possible enhancements how to extend this workflow. 
> - The developers and their new developments should become also a part of Point (A) i think. Stevee shows a good way how a short developer hand out could looks like, take a look in here -->http://wiki.ipfire.org/en/configuration/network/dnsforward . So the coordinator needs to know about this changes too that he can define a priority in the topics.
> - In point (B) shouldn´t be not also the german translations in there as a point (2) ?
> - The testing of the written articles should be mentioned i think, cause it is not enough to understand what this software should do, the software needs to be tested in every single function so a quality management will be done too.
> 	--> I think a new guideline for new and old wikis should be to explain every function which can be seen on the WUI, this means especially the core development or addons where a GUI was also developed by the IPFire team..
> 	--> Addons with foreign documentations can also become a short docu, but they should be linked to the external wiki/docu. This should also be a part of a guideline too.
> 
> A question: Should i start as a coordinator to list some important topics ? Or do we need a little longer ?
> 
> ------------------------
> 
> A guideline of how to structure the content and the layout of the wiki might be important for the workflow i think. This should prevent that people doing very different stuff if they work together in the same sections. So i have found until now 2 different guidelines for the IPFire wiki. 
> 
> - http://wiki.ipfire.org/nonpublic/en/guidelines
> - http://wiki.ipfire.org/en/edit
EDIT:
http://wiki.ipfire.org/en/wiki/syntax
> 
> So some questions to you all regarding to this theme: 
> - What kind of layout and content structure we should use ? 
> - What things are missing in those guidelines ?
> - To make one good guideline please give some suggestions to them.
> 
> Greetings
> 
> Erik
> 
> 
>> I drew a little image on how I image the workflow:
>> http://wiki.ipfire.org/projects/docs/workflow
>> 
>> Maybe we need to define some things more precisely, but I think this is
>> a point were we can start from.
>> 
>> Please post suggestions and critics.
> 

Am 27.07.2013 um 18:00 schrieb Erik K.:

> Hi Michael,
> so for the first i think your workflow looks pretty good, but i have some possible enhancements how to extend this workflow. 
> - The developers and their new developments should become also a part of Point (A) i think. Stevee shows a good way how a short developer hand out could looks like, take a look in here --> http://wiki.ipfire.org/en/configuration/network/dnsforward . So the coordinator needs to know about this changes too that he can define a priority in the topics.
> - In point (B) shouldn´t be not also the german translations in there as a point (2) ?
> - The testing of the written articles should be mentioned i think, cause it is not enough to understand what this software should do, the software needs to be tested in every single function so a quality management will be done too.
> 	--> I think a new guideline for new and old wikis should be to explain every function which can be seen on the WUI, this means especially the core development or addons where a GUI was also developed by the IPFire team..
> 	--> Addons with foreign documentations can also become a short docu, but they should be linked to the external wiki/docu. This should also be a part of a guideline too.
> 
> A question: Should i start as a coordinator to list some important topics ? Or do we need a little longer ?
> 
> ------------------------
> 
> A guideline of how to structure the content and the layout of the wiki might be important for the workflow i think. This should prevent that people doing very different stuff if they work together in the same sections. So i have found until now 2 different guidelines for the IPFire wiki. 
> 
> - http://wiki.ipfire.org/nonpublic/en/guidelines
> - http://wiki.ipfire.org/en/edit
> 
> So some questions to you all regarding to this theme: 
> - What kind of layout and content structure we should use ? 
> - What things are missing in those guidelines ?
> - To make one good guideline please give some suggestions to them.
> 
> Greetings
> 
> Erik
> 
> 
>> I drew a little image on how I image the workflow:
>> http://wiki.ipfire.org/projects/docs/workflow
>> 
>> Maybe we need to define some things more precisely, but I think this is
>> a point were we can start from.
>> 
>> Please post suggestions and critics.
> 
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> http://lists.ipfire.org/mailman/listinfo/documentation

Re: IPFire Wiki Workflow

[Erik K.]

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

Hi Michael,
so for the first i think your workflow looks pretty good, but i have some possible enhancements how to extend this workflow. 
- The developers and their new developments should become also a part of Point (A) i think. Stevee shows a good way how a short developer hand out could looks like, take a look in here --> http://wiki.ipfire.org/en/configuration/network/dnsforward . So the coordinator needs to know about this changes too that he can define a priority in the topics.
- In point (B) shouldn´t be not also the german translations in there as a point (2) ?
- The testing of the written articles should be mentioned i think, cause it is not enough to understand what this software should do, the software needs to be tested in every single function so a quality management will be done too.
	--> I think a new guideline for new and old wikis should be to explain every function which can be seen on the WUI, this means especially the core development or addons where a GUI was also developed by the IPFire team..
	--> Addons with foreign documentations can also become a short docu, but they should be linked to the external wiki/docu. This should also be a part of a guideline too.

A question: Should i start as a coordinator to list some important topics ? Or do we need a little longer ?

------------------------

A guideline of how to structure the content and the layout of the wiki might be important for the workflow i think. This should prevent that people doing very different stuff if they work together in the same sections. So i have found until now 2 different guidelines for the IPFire wiki. 

- http://wiki.ipfire.org/nonpublic/en/guidelines
- http://wiki.ipfire.org/en/edit

So some questions to you all regarding to this theme: 
- What kind of layout and content structure we should use ? 
- What things are missing in those guidelines ?
- To make one good guideline please give some suggestions to them.

Greetings

Erik


> I drew a little image on how I image the workflow:
>  http://wiki.ipfire.org/projects/docs/workflow
> 
> Maybe we need to define some things more precisely, but I think this is
> a point were we can start from.
> 
> Please post suggestions and critics.

Re: IPFire Wiki Workflow

[R. W. Rodolico]

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



On 07/12/2013 07:08 AM, Erik K. wrote:
> Allright,
>> * How do we attract authors? (People who write content)
>> * How do we attract translators? (People who translate the content from
>> English into their respective languages)
>> * How do we decide what to work on? When? For how long?
> 
> for myself this questions are difficult to replay, haven´t found until
> now a clear tendency why people do author or translator work. The
> willing to help is for sure a concern, but the multitude of informations
> and themes which are to care for can also slain this willing, my first
> purpose at this time was to learn more about IPFire but also to support
> a good project, so i started to translate wiki sections from german to
> english and tested also a various amount of addons and functions on the
> basic system of IPFire. 
> I think also what Rod says is important, new users or mostly people from
> the forum feels a high obstacle to change things in the wiki cause they
> think they make something wrong or swipe somebodies work. May some more
> hints in the wiki that everybody is invited to extend own know how can
> may change those attitudes, but we have tried also those rudiments with
> sides like this --> http://wiki.ipfire.org/projects/docs/start and
> references to this side in the wiki, but also by motivating the people
> directly in the forum. The result is the reason of this mailinglist
> theme, so i have not really an answer how we can attract people to work
> more in this topic.

Speaking for me, personally, there are three reasons to want to work on
the documentation.

1) I want to help, and can not devote the necessary time to learn the
skill set to do coding. So, it is either testing or documentation.

2) I need answers to my questions sometimes, and finding them in the
wiki is difficult. So, instead of creating my own separate "cheat sheet"
(which is easier), it is better to have all the notes of myself and
others in one spot.

3) When someone using my routers (which are based on IPFire) wants to do
something, it is nice to have it well documented someplace so they can
simply look it up.

> 
> A possibility to reach more people or to transfer a kind of "wiki
> politic" were everybody is invited to help out in this working area can
> be to write a round mail, like with the core updates, everybody who have
> signed into the forum can be informed in that way. But i don´t know how
> much attraction comes out of that.

Have you ever looked at the official PHP web site (no, Micheal, I KNOW
you probably don't even know it exists)! As an example, see
http://us2.php.net/manual/en/function.strlen.php, a description of the
strlen function. There is the basic description, then at the bottom are
comments by users. As far as I can tell, it is an arbitrated comment
section.

The nice thing about it is, anyone can add comments and anyone can read
them. The document maintainers then apparently review the comments
occasionally and fix errors that are commented on. This would be a way
for any user to add notes, without fear that they would be taking on too
much responsibility for documentation. It is much less intimidating to
the average visitor.

> 
> The decision what to work on should be set by a similar priority like in
> development. If there is a bug in the basic system it is more important
> than a bug in a addon, surely both will be fixed fast ;-) but i want to
> point out that the wiki for the basic system is more important to have
> it complete and well structured i think. Also a good indicator for
> improvements can be to look at the questions in the forum. Before the
> "new" Squid wiki there was really a lot of repeating questions, after
> every single part (function of the WUI) was explained, the questions
> concerning to the proxy in the forum was reduced dramatically. Also the
> possibility to give short help informations only by linking to the
> specific section was a work simplification for supporter in the forum.
> 
> The decision "When" to work on topics should be as soon and
> straight-lined as possible, but to make those decisions, a organized
> team should be available, this takes me back to the question "How do we
> attract people".
> 
> "For How long?": Depends on the theme and also on the amount of helpers
> i think.
> 
>> On your note about that development has to be involved in this as well:
>> Agreed and I already talked to Arne and Stevee how we can do that in the
>> least time consuming way, because we also don't have much time and loads
>> of things to work on.
>> Writing articles in more than one language is an absolute no-go. We will
>> leave it at English and write down the most important things one needs
>> to know about a certain add-on or what ever. Adding screenshots, doing
>> the translations and getting the article into a round shape should be
>> the task of the translation team. Could you guys agree on that?
> 
>> I also think that developers are not the best people to write end-user
>> documentation. It is getting to complex and not suitable for beginners
>> any way.
> 
> Not only You Arne and Stevee should follow those rules, also addon
> developers, or development in general. Sorry for the worse link to
> Wikipedia
> --> https://en.wikipedia.org/wiki/Software_documentation#Role_of_documentation_in_software_development but
> i think in there are some good statements why documentation in software
> development are very important and also a inherent part of development.
> If it is in german or in english is for now secondary i think. All
> developed functions needs to be explained in there, otherwise how should
> a possible documentation team knows what they have to write for.
> Screenshoots, the layout stuff, the literarily consolidation and
> translation should be the very own of an documentation team i think, so
> far i can agree with you. But a good documentation hand out of new
> development is the basic of a better documentation i think. Time is
> always a problem for all, since this project is a non commercial one,
> nobody can live by working in full time in this project, but it
> shouldn´t be a whitewash for incompleteness. 

Part of any change to the UI or functionality should be passed on to the
documentation team by the developers. This should be part of the alpha
testing of a modification. The documentation should be updated as part
of the beta process (or earlier).

One though crossed my mind. We need developers to develop, and there are
not enough documenters. If we had a comment section, the developers
could simply make a brief statement in the comments that something had
changed. Even if the documenters did not get a particular page updated
before release, there would still be notes there. It is sloppy, but
allows developers to develop and takes into account the fact there are
not many active documenters.

> 
> So an idea can be to have an closer contact from the developer team to a
> possible documentation team, to ensure this knowledge transfer. This can
> also be attractive for new helpers to stay a little closer to the matter.
> 
> 
> Erik
> 
> 
> 
> Am 12.07.2013 um 00:01 schrieb Michael Tremer:
> 
>> Great thoughts, but let's bring down the pace a little bit before we
>> start talking about the actual content that needs to be reviewed and
>> possibly (re-written).
>>
>> I am still aiming for defining a workflow in this discussion that should
>> be followed under all circumstance, because I think this is what is most
>> important on a team, that we are all on the "same page" (almost
>> literally in this context).
>>
>> Central questions are:
>>
>> * How do we attract authors? (People who write content)
>> * How do we attract translators? (People who translate the content from
>> English into their respective languages)
>> * How do we decide what to work on? When? For how long?
>>
>> The has to be a "team", otherwise we don't need to think about the
>> content.
>>
>> On your note about that development has to be involved in this as well:
>> Agreed and I already talked to Arne and Stevee how we can do that in the
>> least time consuming way, because we also don't have much time and loads
>> of things to work on.
>> Writing articles in more than one language is an absolute no-go. We will
>> leave it at English and write down the most important things one needs
>> to know about a certain add-on or what ever. Adding screenshots, doing
>> the translations and getting the article into a round shape should be
>> the task of the translation team. Could you guys agree on that?
>>
>> I also think that developers are not the best people to write end-user
>> documentation. It is getting to complex and not suitable for beginners
>> any way.
>>
>> -Michael
>>
>> On Thu, 2013-07-11 at 19:30 +0200, Erik K. wrote:
>>> Hi all,
>>> regarding to the ideas causing a better overview of the wiki content,
>>> i have tried a more compressed layout of the configuration wiki. The
>>> actual (official) look of this section can be found in here
>>> --> http://wiki.ipfire.org/en/configuration/start . 
>>> The new one is very unready and only a first try, but it should show
>>> an idea how it could be better overviewed. 
>>> In here --> http://wiki.ipfire.org/en/configuration/start you belong
>>> to the new structure.
>>> Until now there is no content behind the structure but this should be
>>> done fast by a copy and paste of the old content. <-- Better to check
>>> out some sections before. Another possibility in this kind of
>>> structure can be to work more precised in themes with e.g. 5-10
>>> different sections not as before with 40-50 (example in here
>>> --> http://wiki.ipfire.org/en/configuration/start ).
>>>
>>> A statement to the wiki workflow:
>>> In the last months, mostly work was done in particular articles of
>>> the wiki, also to clean up the code cause a lot of plugins was
>>> replaced, so the general structure wasn´t touched but becomes more
>>> and more informations. I think most important is for the first
>>> * Find out a new structure which can be better overviewed
>>> (configuration and installation, ???).
>>> * Go for a checkout of the basic system articles (without addons) and
>>> find out the worse sections to make them better and clearer.
>>> * If old articles will be revised, the explained functions should
>>> also be tested.
>>> * Documentation should be a part of the development of software (and
>>> if it is only a short developer hand out) so a possible documentation
>>> "team" have it easier.
>>>
>>> Also to overview the actual changes in the wiki needs to be checked.
>>> In here --> http://wiki.ipfire.org/start?do=recent a done list can be
>>> overviewed. If there was a change in german, it might be great to
>>> find it also in the english wiki. As more people looks in there as
>>> better it is.
>>>
>>> The native speakers: It is very important to have some people
>>> especial in english (american/english). The best might be that some
>>> people are native in two languages german/english otherwise we have
>>> the same condition than before. I tried always my best as an native
>>> german speaker to translate the wikis into english, but thats not
>>> enough for a good feeling by reading. So i tried always to send some
>>> messages over the docu mailinglist with the please that someone can
>>> go for corrections (also in german). Sometimes this kind of workflow
>>> did it very good (thanks again Rod by the way ;-), but sometimes
>>> (especially in the last past months) there was no response. As time
>>> goes by the wiki articles leaves the memory that there was something
>>> to do and they where forgotten. So it is maybe an idea to mark those
>>> articles as "uncheck, everybody is invited to go for a revise" or
>>> something.
>>>
>>> So for the first some ideas from me.
>>>
>>>
>>> Greetings 
>>>
>>>
>>> Erik
>>> _______________________________________________
>>> Documentation mailing list
>>> Documentation(a)lists.ipfire.org <mailto:Documentation(a)lists.ipfire.org>
>>> http://lists.ipfire.org/mailman/listinfo/documentation
>>
>>
> 
> 
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> http://lists.ipfire.org/mailman/listinfo/documentation
> 

-- 
R. W. "Rod" Rodolico
Daily Data, Inc.
POB 140465
Dallas TX 75214-0465
http://www.dailydata.net
214.827.2170


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: rodo.vcf --]
[-- Type: text/x-vcard, Size: 233 bytes --]

begin:vcard
fn:R. W. Rodolico
n:Rodolico;R. W.
org:Daily Data, Inc.
adr:;;POB 140465;Dallas;TX;75214-0465;US
email;internet:rodo@dailydata.net
title:President
tel;work:214.827.2170
url:http://www.dailydata.net
version:2.1
end:vcard

Re: IPFire Wiki Workflow

[Michael Tremer]

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

On Fri, 2013-07-12 at 14:08 +0200, Erik K. wrote:
> Allright,
> > * How do we attract authors? (People who write content)
> > * How do we attract translators? (People who translate the content
> > from
> > English into their respective languages)
> > * How do we decide what to work on? When? For how long?
> 
> for myself this questions are difficult to replay, haven´t found until
> now a clear tendency why people do author or translator work. The
> willing to help is for sure a concern, but the multitude of
> informations and themes which are to care for can also slain this
> willing, my first purpose at this time was to learn more about IPFire
> but also to support a good project, so i started to translate wiki
> sections from german to english and tested also a various amount of
> addons and functions on the basic system of IPFire. 
> I think also what Rod says is important, new users or mostly people
> from the forum feels a high obstacle to change things in the wiki
> cause they think they make something wrong or swipe somebodies work.
> May some more hints in the wiki that everybody is invited to extend
> own know how can may change those attitudes, but we have tried also
> those rudiments with sides like this -->
> http://wiki.ipfire.org/projects/docs/start and references to this side
> in the wiki, but also by motivating the people directly in the forum.
> The result is the reason of this mailinglist theme, so i have not
> really an answer how we can attract people to work more in this topic.

One central thought on why people should write documentation because it
is a fun job that gets yourself involved into the project. You work on a
team that creates something a lot of people benefit from. For me this is
very important that people see or use what I have been working on. This
is not something I do only for me.

You wouldn't need very deep understanding how the IPFire system works
like you would need when being a developer. But you may have skills that
are very important to the project like speaking a different language or
the ability to write good texts that are easily understandable.

> A possibility to reach more people or to transfer a kind of "wiki
> politic" were everybody is invited to help out in this working area
> can be to write a round mail, like with the core updates, everybody
> who have signed into the forum can be informed in that way. But i don
> ´t know how much attraction comes out of that.

Being open and allowing everyone to join is not only a set of mind for
the wiki, but the entire IPFire project.

Yes, we can prepare an email to everybody that invites them to take part
in the documentation team, but we need to bring reasons why the should
do it.
Could someone prepare a list of reasons that will help to motivate
people? I would volunteer for writing the email.

> The decision what to work on should be set by a similar priority like
> in development. If there is a bug in the basic system it is more
> important than a bug in a addon, surely both will be fixed fast ;-)
> but i want to point out that the wiki for the basic system is more
> important to have it complete and well structured i think. Also a good
> indicator for improvements can be to look at the questions in the
> forum. Before the "new" Squid wiki there was really a lot of repeating
> questions, after every single part (function of the WUI) was
> explained, the questions concerning to the proxy in the forum was
> reduced dramatically. Also the possibility to give short help
> informations only by linking to the specific section was a work
> simplification for supporter in the forum.

In development, there are several ways in how we handle things which
almost entirely depend on how urgent something is. Some things are fixed
almost immediately after they have been spotted. Others are put on a
list and get fixed later. For some things, we work out bigger schedules.

Put that seconds thought on the list above.

> The decision "When" to work on topics should be as soon and
> straight-lined as possible, but to make those decisions, a organized
> team should be available, this takes me back to the question "How do
> we attract people".
> 
> "For How long?": Depends on the theme and also on the amount of
> helpers i think.

I drew a little image on how I image the workflow:
  http://wiki.ipfire.org/projects/docs/workflow

Maybe we need to define some things more precisely, but I think this is
a point were we can start from.

Please post suggestions and critics.

> > On your note about that development has to be involved in this as
> > well:
> > Agreed and I already talked to Arne and Stevee how we can do that in
> > the
> > least time consuming way, because we also don't have much time and
> > loads
> > of things to work on.
> > Writing articles in more than one language is an absolute no-go. We
> > will
> > leave it at English and write down the most important things one
> > needs
> > to know about a certain add-on or what ever. Adding screenshots,
> > doing
> > the translations and getting the article into a round shape should
> > be
> > the task of the translation team. Could you guys agree on that?
> 
> > I also think that developers are not the best people to write
> > end-user
> > documentation. It is getting to complex and not suitable for
> > beginners
> > any way.
> 
> Not only You Arne and Stevee should follow those rules, also addon
> developers, or development in general. Sorry for the worse link to
> Wikipedia -->
> https://en.wikipedia.org/wiki/Software_documentation#Role_of_documentation_in_software_development but i think in there are some good statements why documentation in software development are very important and also a inherent part of development. If it is in german or in english is for now secondary i think. All developed functions needs to be explained in there, otherwise how should a possible documentation team knows what they have to write for. Screenshoots, the layout stuff, the literarily consolidation and translation should be the very own of an documentation team i think, so far i can agree with you. But a good documentation hand out of new development is the basic of a better documentation i think. Time is always a problem for all, since this project is a non commercial one, nobody can live by working in full time in this project, but it shouldn´t be a whitewash for incompleteness. 

Yeah, certainly this is an important part. But as we don't have too much
man power in development either and therefore is every minute that goes
into documentation cutting back in development.

I personally don't want that and so, we have to find a way that's in
between those two options.

> So an idea can be to have an closer contact from the developer team to
> a possible documentation team, to ensure this knowledge transfer. This
> can also be attractive for new helpers to stay a little closer to the
> matter.

I would like to postpone this part of the discussion until we have the
documentation team up and running again. I am not sure that a set of
rules would work here.

> 
> 
> Erik
> 
> 
> 
> Am 12.07.2013 um 00:01 schrieb Michael Tremer:
> 
> > Great thoughts, but let's bring down the pace a little bit before we
> > start talking about the actual content that needs to be reviewed and
> > possibly (re-written).
> > 
> > I am still aiming for defining a workflow in this discussion that
> > should
> > be followed under all circumstance, because I think this is what is
> > most
> > important on a team, that we are all on the "same page" (almost
> > literally in this context).
> > 
> > Central questions are:
> > 
> > * How do we attract authors? (People who write content)
> > * How do we attract translators? (People who translate the content
> > from
> > English into their respective languages)
> > * How do we decide what to work on? When? For how long?
> > 
> > The has to be a "team", otherwise we don't need to think about the
> > content.
> > 
> > On your note about that development has to be involved in this as
> > well:
> > Agreed and I already talked to Arne and Stevee how we can do that in
> > the
> > least time consuming way, because we also don't have much time and
> > loads
> > of things to work on.
> > Writing articles in more than one language is an absolute no-go. We
> > will
> > leave it at English and write down the most important things one
> > needs
> > to know about a certain add-on or what ever. Adding screenshots,
> > doing
> > the translations and getting the article into a round shape should
> > be
> > the task of the translation team. Could you guys agree on that?
> > 
> > I also think that developers are not the best people to write
> > end-user
> > documentation. It is getting to complex and not suitable for
> > beginners
> > any way.
> > 
> > -Michael
> > 
> > On Thu, 2013-07-11 at 19:30 +0200, Erik K. wrote:
> > > Hi all,
> > > regarding to the ideas causing a better overview of the wiki
> > > content, i have tried a more compressed layout of the
> > > configuration wiki. The actual (official) look of this section can
> > > be found in here
> > > --> http://wiki.ipfire.org/en/configuration/start . 
> > > The new one is very unready and only a first try, but it should
> > > show an idea how it could be better overviewed. 
> > > In here --> http://wiki.ipfire.org/en/configuration/start you
> > > belong to the new structure.
> > > Until now there is no content behind the structure but this should
> > > be done fast by a copy and paste of the old content. <-- Better to
> > > check out some sections before. Another possibility in this kind
> > > of structure can be to work more precised in themes with e.g. 5-10
> > > different sections not as before with 40-50 (example in here
> > > --> http://wiki.ipfire.org/en/configuration/start ).
> > > 
> > > A statement to the wiki workflow:
> > > In the last months, mostly work was done in particular articles of
> > > the wiki, also to clean up the code cause a lot of plugins was
> > > replaced, so the general structure wasn´t touched but becomes more
> > > and more informations. I think most important is for the first
> > > * Find out a new structure which can be better overviewed
> > > (configuration and installation, ???).
> > > * Go for a checkout of the basic system articles (without addons)
> > > and find out the worse sections to make them better and clearer.
> > > * If old articles will be revised, the explained functions should
> > > also be tested.
> > > * Documentation should be a part of the development of software
> > > (and if it is only a short developer hand out) so a possible
> > > documentation "team" have it easier.
> > > 
> > > Also to overview the actual changes in the wiki needs to be
> > > checked. In here --> http://wiki.ipfire.org/start?do=recent a done
> > > list can be overviewed. If there was a change in german, it might
> > > be great to find it also in the english wiki. As more people looks
> > > in there as better it is.
> > > 
> > > The native speakers: It is very important to have some people
> > > especial in english (american/english). The best might be that
> > > some people are native in two languages german/english otherwise
> > > we have the same condition than before. I tried always my best as
> > > an native german speaker to translate the wikis into english, but
> > > thats not enough for a good feeling by reading. So i tried always
> > > to send some messages over the docu mailinglist with the please
> > > that someone can go for corrections (also in german). Sometimes
> > > this kind of workflow did it very good (thanks again Rod by the
> > > way ;-), but sometimes (especially in the last past months) there
> > > was no response. As time goes by the wiki articles leaves the
> > > memory that there was something to do and they where forgotten. So
> > > it is maybe an idea to mark those articles as "uncheck, everybody
> > > is invited to go for a revise" or something.
> > > 
> > > So for the first some ideas from me.
> > > 
> > > 
> > > Greetings 
> > > 
> > > 
> > > Erik
> > > _______________________________________________
> > > Documentation mailing list
> > > Documentation(a)lists.ipfire.org
> > > http://lists.ipfire.org/mailman/listinfo/documentation
> > 
> > 
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> http://lists.ipfire.org/mailman/listinfo/documentation

Re: IPFire Wiki Workflow

[embp]

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


Am 12.07.2013 um 14:03 schrieb Erik K.:

> Allright,
>> * How do we attract authors? (People who write content)
>> * How do we attract translators? (People who translate the content from
>> English into their respective languages)
>> * How do we decide what to work on? When? For how long?
> 
> for myself this questions are difficult to replay, haven´t found until now a clear tendency why people do author or translator work. The willing to help is for sure a concern, but the multitude of informations and themes which are to care for can also slain this willing, my first purpose at this time was to learn more about IPFire but also to support a good project, so i started to translate wiki sections from german to english and tested also a various amount of addons and functions on the basic system of IPFire. 
> I think also what Rod says is important, new users or mostly people from the forum feels a high obstacle to change things in the wiki cause they think they make something wrong or swipe somebodies work. May some more hints in the wiki that everybody is invited to extend own know how can may change those attitudes, but we have tried also those rudiments with sides like this --> http://wiki.ipfire.org/projects/docs/start and references to this side in the wiki, but also by motivating the people directly in the forum. The result is the reason of this mailinglist theme, so i have not really an answer how we can attract people to work more in this topic.
> 
> A possibility to reach more people or to transfer a kind of "wiki politic" were everybody is invited to help out in this working area can be to write a round mail, like with the core updates, everybody who have signed into the forum can be informed in that way. But i don´t know how much attraction comes out of that.
> 
> The decision what to work on should be set by a similar priority like in development. If there is a bug in the basic system it is more important than a bug in a addon, surely both will be fixed fast ;-) but i want to point out that the wiki for the basic system is more important to have it complete and well structured i think. Also a good indicator for improvements can be to look at the questions in the forum. Before the "new" Squid wiki there was really a lot of repeating questions, after every single part (function of the WUI) was explained, the questions concerning to the proxy in the forum was reduced dramatically. Also the possibility to give short help informations only by linking to the specific section was a work simplification for supporter in the forum.
> 
> The decision "When" to work on topics should be as soon and straight-lined as possible, but to make those decisions, a organized team should be available, this takes me back to the question "How do we attract people".
> 
> "For How long?": Depends on the theme and also on the amount of helpers i think.
> 
>> On your note about that development has to be involved in this as well:
>> Agreed and I already talked to Arne and Stevee how we can do that in the
>> least time consuming way, because we also don't have much time and loads
>> of things to work on.
>> Writing articles in more than one language is an absolute no-go. We will
>> leave it at English and write down the most important things one needs
>> to know about a certain add-on or what ever. Adding screenshots, doing
>> the translations and getting the article into a round shape should be
>> the task of the translation team. Could you guys agree on that?
> 
>> I also think that developers are not the best people to write end-user
>> documentation. It is getting to complex and not suitable for beginners
>> any way.
> 
> Not only You Arne and Stevee should follow those rules, also addon developers, or development in general. Sorry for the worse link to Wikipedia --> https://en.wikipedia.org/wiki/Software_documentation#Role_of_documentation_in_software_development but i think in there are some good statements why documentation in software development are very important and also a inherent part of development. If it is in german or in english is for now secondary i think. All developed functions needs to be explained in there, otherwise how should a possible documentation team knows what they have to write for. Screenshoots, the layout stuff, the literarily consolidation and translation should be the very own of an documentation team i think, so far i can agree with you. But a good documentation hand out of new development is the basic of a better documentation i think. Time is always a problem for all, since this project is a non commercial one, nobody can live by working in full time in this project, but it shouldn´t be a whitewash for incompleteness. 
> 
> So an idea can be to have an closer contact from the developer team to a possible documentation team, to ensure this knowledge transfer. This can also be attractive for new helpers to stay a little closer to the matter.
> 
> 
> Erik
> 
> 
> 
> Am 12.07.2013 um 00:01 schrieb Michael Tremer:
> 
>> Great thoughts, but let's bring down the pace a little bit before we
>> start talking about the actual content that needs to be reviewed and
>> possibly (re-written).
>> 
>> I am still aiming for defining a workflow in this discussion that should
>> be followed under all circumstance, because I think this is what is most
>> important on a team, that we are all on the "same page" (almost
>> literally in this context).
>> 
>> Central questions are:
>> 
>> * How do we attract authors? (People who write content)
>> * How do we attract translators? (People who translate the content from
>> English into their respective languages)
>> * How do we decide what to work on? When? For how long?
>> 
>> The has to be a "team", otherwise we don't need to think about the
>> content.
>> 
>> On your note about that development has to be involved in this as well:
>> Agreed and I already talked to Arne and Stevee how we can do that in the
>> least time consuming way, because we also don't have much time and loads
>> of things to work on.
>> Writing articles in more than one language is an absolute no-go. We will
>> leave it at English and write down the most important things one needs
>> to know about a certain add-on or what ever. Adding screenshots, doing
>> the translations and getting the article into a round shape should be
>> the task of the translation team. Could you guys agree on that?
>> 
>> I also think that developers are not the best people to write end-user
>> documentation. It is getting to complex and not suitable for beginners
>> any way.
>> 
>> -Michael
>> 
>> On Thu, 2013-07-11 at 19:30 +0200, Erik K. wrote:
>>> Hi all,
>>> regarding to the ideas causing a better overview of the wiki content, i have tried a more compressed layout of the configuration wiki. The actual (official) look of this section can be found in here --> http://wiki.ipfire.org/en/configuration/start . 
>>> The new one is very unready and only a first try, but it should show an idea how it could be better overviewed. 
>>> In here --> http://wiki.ipfire.org/en/configuration/start you belong to the new structure.
>>> Until now there is no content behind the structure but this should be done fast by a copy and paste of the old content. <-- Better to check out some sections before. Another possibility in this kind of structure can be to work more precised in themes with e.g. 5-10 different sections not as before with 40-50 (example in here --> http://wiki.ipfire.org/en/configuration/start ).
>>> 
>>> A statement to the wiki workflow:
>>> In the last months, mostly work was done in particular articles of the wiki, also to clean up the code cause a lot of plugins was replaced, so the general structure wasn´t touched but becomes more and more informations. I think most important is for the first
>>> 	* Find out a new structure which can be better overviewed (configuration and installation, ???).
>>> 	* Go for a checkout of the basic system articles (without addons) and find out the worse sections to make them better and clearer.
>>> 	* If old articles will be revised, the explained functions should also be tested.
>>> 	* Documentation should be a part of the development of software (and if it is only a short developer hand out) so a possible documentation "team" have it easier.
>>> 
>>> Also to overview the actual changes in the wiki needs to be checked. In here --> http://wiki.ipfire.org/start?do=recent a done list can be overviewed. If there was a change in german, it might be great to find it also in the english wiki. As more people looks in there as better it is.
>>> 
>>> The native speakers: It is very important to have some people especial in english (american/english). The best might be that some people are native in two languages german/english otherwise we have the same condition than before. I tried always my best as an native german speaker to translate the wikis into english, but thats not enough for a good feeling by reading. So i tried always to send some messages over the docu mailinglist with the please that someone can go for corrections (also in german). Sometimes this kind of workflow did it very good (thanks again Rod by the way ;-), but sometimes (especially in the last past months) there was no response. As time goes by the wiki articles leaves the memory that there was something to do and they where forgotten. So it is maybe an idea to mark those articles as "uncheck, everybody is invited to go for a revise" or something.
>>> 
>>> So for the first some ideas from me.
>>> 
>>> 
>>> Greetings 
>>> 
>>> 
>>> Erik
>>> _______________________________________________
>>> Documentation mailing list
>>> Documentation(a)lists.ipfire.org
>>> http://lists.ipfire.org/mailman/listinfo/documentation
>> 
>> 
>