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
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@ipfire.org An: documentation@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:
- 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.
- 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.
- 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@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
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
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:
- 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.
- 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.
- 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@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
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
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
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
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
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@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
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
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
I figure now is the point that I should input somewhat into Michael's thoughts on the Wiki and documentation.
For those of you who don't me, I'm Aaron (AzzyChill) online and have created one video on IPFire with the plan to develop more in future. I am relatively new to the IPFire project having only really used Untangle for my corporate clients due to its ease of use for both me as an IT support person and my clients as end users of the system I install.
I mentioned recently in my regular Brew Time segments that IPFire is an amazing project but the support available isn't as good as it could be and so it could put a lot of people off, both seasoned IT professionals and noobs who are going into IT pretty clueless as to what they're doing.
I think before re-writing documentation and looking at what support is available and how it can be improved it might be worth first looking at how we (stakeholders & developers) see the project going and what plans it has for the future. The reason for this is so you can tailor any improvement to that end goal.
I pretty much agree with everything that Michael has said including the bits about language. I am from the UK and hence English is my native language, due to failings in the education system of the UK it is also my only language. One would assume that most residents of Germany speak English as well and so starting from English probably isn't a bad idea. But language links in with the end plan and the future for IPFire because currently the majority of your users are based in Germany and speak German and so it would make sense to write everything in German and then translate it to other languages. But if the plan is to try and expand the project to other markets internationally English would be the best language to use because it is an international language.
Now far be it from me to tell you what you should and shouldn't do and to criticise what currently exists as a newcomer but personally I think the support side of the project needs a reasonable amount of work. It needs to be noob friendly, obviously not too basic but it needs to point people in the right direction if they don't know what terms mean. I do think it needs to be written by end users with direction and guidance from developers on how to do stuff because developers knowing the product inside out make assumptions on their users (this happens in IT all the time). There also needs to be a breakdown of what every option does including data entry fields for things like QoS or Proxies etc... and a comprehensive support document/wiki on what it does and how to use it.
All of the above should also tie in with the support forum and to a certain extent Social Media so you can answer questions from the community and potentially corporate clients who may pay for a service (this is me just thinking aloud about how the project could evolve). I also think the use of video is paramount to show users how to do things with IPFire. What I'm trying to do for both my subscribers and for the IPFire community is create a series of videos detailing how to do certain things with IPFire and a few geeky tips on what they do in a real world environment.
Hopefully I've not confused anybody or slagged anybody off but those are just my thoughts on the whole thing. I'd appreciate feedback (if you haven't already) on my IPFire setup video so I can look at how I can improve things in future IPFire videos http://youtu.be/u7-qKaI78TM
Aaron Philpott
On 12 July 2013 16:02, Michael Tremer michael.tremer@ipfire.org wrote:
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
Documentation mailing list Documentation@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
On Fri, 2013-07-12 at 17:55 +0100, Aaron Philpott wrote:
I figure now is the point that I should input somewhat into Michael's thoughts on the Wiki and documentation.
For those of you who don't me, I'm Aaron (AzzyChill) online and have created one video on IPFire with the plan to develop more in future. I am relatively new to the IPFire project having only really used Untangle for my corporate clients due to its ease of use for both me as an IT support person and my clients as end users of the system I install.
Welcome :)
I mentioned recently in my regular Brew Time segments that IPFire is an amazing project but the support available isn't as good as it could be and so it could put a lot of people off, both seasoned IT professionals and noobs who are going into IT pretty clueless as to what they're doing.
What made me realize that we have to do more about documentation and these things was seeing you being confused about how to install IPFire. It's not that you don't have the general knowledge about how to do things, but of course you don't have a clue *where* to start when you install IPFire for the first time.
Being not too noob-friendly is okay and to some extend I think we should not be too noob-friendly because firewalls are not for noobs. But lacking essential information for all other people who start with IPFire is not okay.
I pretty much agree with everything that Michael has said including the bits about language. I am from the UK and hence English is my native language, due to failings in the education system of the UK it is also my only language. One would assume that most residents of Germany speak English as well and so starting from English probably isn't a bad idea. But language links in with the end plan and the future for IPFire because currently the majority of your users are based in Germany and speak German and so it would make sense to write everything in German and then translate it to other languages. But if the plan is to try and expand the project to other markets internationally English would be the best language to use because it is an international language.
That's exactly the point and I don't understand all the fuzz about the language. People in America and the UK speak English. Nothing else. All the rest of Europe and the Americas and parts of Asia are used to communicate in English (at least reading). All other Open Source projects are in English. There is not a single major project I know that is not running in English.
And English is also the language for development in the IPFire project. We use it in Bugzilla, we use it on our mailing lists, we use it everywhere. The majority of the people who use IPFire is not from Germany, so there is absolutely no point in choosing any other language than English.
-Michael
Gesendet: Samstag, 13. Juli 2013 um 18:20 Uhr Von: "Michael Tremer" michael.tremer@ipfire.org An: documentation@lists.ipfire.org Betreff: Re: Aw: Re: IPFire Wiki Workflow
The majority of the people who use IPFire is not from Germany, so there is absolutely no point in choosing any other language than English.
That's not really true, http://fireinfo.ipfire.org/stats/geo states that 51% of the systems use German. I suppose this the language the admin is used to. The numbers about countries show an similiar value ( Germany+Austria+Switzerland*2/3 ). Don't want to restart this discussion, but computer science is an exact science and I'm used to work in this manner.
Beware that we don't have the data of all IPFire systems. Fireinfo is disabled by default and you will need to enable it after the installation. Therefore this data is not 100% accurate.
Since we started fireinfo, the amount of systems running in Germany is decreasing. We are now at 50:50.
So 51% German is not a majority. It's equally distributed and German is decreasing.
-Michael
On Sun, 2013-07-14 at 22:00 +0200, Bernhard Bitsch wrote:
Gesendet: Samstag, 13. Juli 2013 um 18:20 Uhr Von: "Michael Tremer" michael.tremer@ipfire.org An: documentation@lists.ipfire.org Betreff: Re: Aw: Re: IPFire Wiki Workflow
The majority of the people who use IPFire is not from Germany, so there is absolutely no point in choosing any other language than English.
That's not really true, http://fireinfo.ipfire.org/stats/geo states that 51% of the systems use German. I suppose this the language the admin is used to. The numbers about countries show an similiar value ( Germany+Austria+Switzerland*2/3 ). Don't want to restart this discussion, but computer science is an exact science and I'm used to work in this manner.
Any reason why this discussion has ended without a result?
Are there any suggestions/opinions about the proposed workflow? Can't believe that there is nothing to talk about...
-Michael
On Sat, 2013-07-13 at 18:20 +0200, Michael Tremer wrote:
On Fri, 2013-07-12 at 17:55 +0100, Aaron Philpott wrote:
I figure now is the point that I should input somewhat into Michael's thoughts on the Wiki and documentation.
For those of you who don't me, I'm Aaron (AzzyChill) online and have created one video on IPFire with the plan to develop more in future. I am relatively new to the IPFire project having only really used Untangle for my corporate clients due to its ease of use for both me as an IT support person and my clients as end users of the system I install.
Welcome :)
I mentioned recently in my regular Brew Time segments that IPFire is an amazing project but the support available isn't as good as it could be and so it could put a lot of people off, both seasoned IT professionals and noobs who are going into IT pretty clueless as to what they're doing.
What made me realize that we have to do more about documentation and these things was seeing you being confused about how to install IPFire. It's not that you don't have the general knowledge about how to do things, but of course you don't have a clue *where* to start when you install IPFire for the first time.
Being not too noob-friendly is okay and to some extend I think we should not be too noob-friendly because firewalls are not for noobs. But lacking essential information for all other people who start with IPFire is not okay.
I pretty much agree with everything that Michael has said including the bits about language. I am from the UK and hence English is my native language, due to failings in the education system of the UK it is also my only language. One would assume that most residents of Germany speak English as well and so starting from English probably isn't a bad idea. But language links in with the end plan and the future for IPFire because currently the majority of your users are based in Germany and speak German and so it would make sense to write everything in German and then translate it to other languages. But if the plan is to try and expand the project to other markets internationally English would be the best language to use because it is an international language.
That's exactly the point and I don't understand all the fuzz about the language. People in America and the UK speak English. Nothing else. All the rest of Europe and the Americas and parts of Asia are used to communicate in English (at least reading). All other Open Source projects are in English. There is not a single major project I know that is not running in English.
And English is also the language for development in the IPFire project. We use it in Bugzilla, we use it on our mailing lists, we use it everywhere. The majority of the people who use IPFire is not from Germany, so there is absolutely no point in choosing any other language than English.
-Michael
Documentation mailing list Documentation@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
I don't see anything wrong with it.
I say lets do it!
On 19 July 2013 13:46, Michael Tremer michael.tremer@ipfire.org wrote:
Any reason why this discussion has ended without a result?
Are there any suggestions/opinions about the proposed workflow? Can't believe that there is nothing to talk about...
-Michael
On Sat, 2013-07-13 at 18:20 +0200, Michael Tremer wrote:
On Fri, 2013-07-12 at 17:55 +0100, Aaron Philpott wrote:
I figure now is the point that I should input somewhat into Michael's thoughts on the Wiki and documentation.
For those of you who don't me, I'm Aaron (AzzyChill) online and have created one video on IPFire with the plan to develop more in future. I am relatively new to the IPFire project having only really used Untangle for my corporate clients due to its ease of use for both me as an IT support person and my clients as end users of the system I install.
Welcome :)
I mentioned recently in my regular Brew Time segments that IPFire is an amazing project but the support available isn't as good as it could be and so it could put a lot of people off, both seasoned IT professionals and noobs who are going into IT pretty clueless as to what they're doing.
What made me realize that we have to do more about documentation and these things was seeing you being confused about how to install IPFire. It's not that you don't have the general knowledge about how to do things, but of course you don't have a clue *where* to start when you install IPFire for the first time.
Being not too noob-friendly is okay and to some extend I think we should not be too noob-friendly because firewalls are not for noobs. But lacking essential information for all other people who start with IPFire is not okay.
I pretty much agree with everything that Michael has said including the bits about language. I am from the UK and hence English is my native language, due to failings in the education system of the UK it is also my only language. One would assume that most residents of Germany speak English as well and so starting from English probably isn't a bad idea. But language links in with the end plan and the future for IPFire because currently the majority of your users are based in Germany and speak German and so it would make sense to write everything in German and then translate it to other languages. But if the plan is to try and expand the project to other markets internationally English would be the best language to use because it is an international language.
That's exactly the point and I don't understand all the fuzz about the language. People in America and the UK speak English. Nothing else. All the rest of Europe and the Americas and parts of Asia are used to communicate in English (at least reading). All other Open Source projects are in English. There is not a single major project I know that is not running in English.
And English is also the language for development in the IPFire project. We use it in Bugzilla, we use it on our mailing lists, we use it everywhere. The majority of the people who use IPFire is not from Germany, so there is absolutely no point in choosing any other language than English.
-Michael
Documentation mailing list Documentation@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
Documentation mailing list Documentation@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
Hi all, sorry for the longer time of silence from my side, but i was on the way in the last days.
@Aaron, i have seen your video and i think it is a very nice one. It was held short, and explains a lot of important stuff. How do you think to proceed further ? Should there be a kind of structure like in the wiki --> 1) Installation, 2) Configuration, 3) Addons or something like this ?
I mentioned recently in my regular Brew Time segments that IPFire is an amazing project but the support available isn't as good as it could be and so it could put a lot of people off, both seasoned IT professionals and noobs who are going into IT pretty clueless as to what they're doing.
Regarding to the support, i think you are pretty right in that case. To support a project like IPFire it is important to have more know-how that a normal user have, cause a lot of threads and a potential help in there needs a deeper knowledge about how IPFire works. Also to know where to find all the different platforms like the bugtracker, Git, the mailinglists and of course the different wiki´s there is also the need to stay a little deeper in the project structure and also to know what to do if special situations are happening (for example a bug was found what to do now). So in my eyes a good supporter isn´t born by a amount of more than 250 posts. Probably the work in a possible documentation group can bring some further know-how of the project ?!?!
What made me realize that we have to do more about documentation and these things was seeing you being confused about how to install IPFire. It's not that you don't have the general knowledge about how to do things, but of course you don't have a clue *where* to start when you install IPFire for the first time.
Being not too noob-friendly is okay and to some extend I think we should not be too noob-friendly because firewalls are not for noobs. But lacking essential information for all other people who start with IPFire is not okay.
The information about what essentials lacks are very important i think. As longer you stay in project, as more things are difficult to see objectively from an eye of a beginner. May a list what essentials this are, can be very helpful. So if you have some points it might be great if you can list them.
I pretty much agree with everything that Michael has said including the bits about language. I am from the UK and hence English is my native language, due to failings in the education system of the UK it is also my only language. One would assume that most residents of Germany speak English as well and so starting from English probably isn't a bad idea. But language links in with the end plan and the future for IPFire because currently the majority of your users are based in Germany and speak German and so it would make sense to write everything in German and then translate it to other languages. But if the plan is to try and expand the project to other markets internationally English would be the best language to use because it is an international language.
So we tried both in past. Mostly native germans who made some wiki articles made them in german, we have tried then to write those people that they go for a translation to english which was sometimes difficult to achieve. So i/we have tried to make this part of work too. Back in the days where i engage to the wiki work, 80 % of the addons was made in german language and the work at this time was to adjust the english wiki to the german. If people are willing to make some articles in the wiki (they are free to do so with a forum account), they make it rarely in both languages but mostly in their home language. So it is difficult to make sure that they make both or at least only in english.
I need to confess that i do new articles also first in german cause i can better think about enhancements during the writing, also the kind of writing is pretty much different as if i do it first in english, this is surely because i´am not a pretty good english speaker and i don´t think in english language when i write articles, but this is may also a thing of practice. Will try it more in this way.
So some thoughts from my side to this theme.
Greetings
Erik
Am 19.07.2013 um 21:45 schrieb Aaron Philpott:
I don't see anything wrong with it.
I say lets do it!
On 19 July 2013 13:46, Michael Tremer michael.tremer@ipfire.org wrote: Any reason why this discussion has ended without a result?
Are there any suggestions/opinions about the proposed workflow? Can't believe that there is nothing to talk about...
-Michael
On Sat, 2013-07-13 at 18:20 +0200, Michael Tremer wrote:
On Fri, 2013-07-12 at 17:55 +0100, Aaron Philpott wrote:
I figure now is the point that I should input somewhat into Michael's thoughts on the Wiki and documentation.
For those of you who don't me, I'm Aaron (AzzyChill) online and have created one video on IPFire with the plan to develop more in future. I am relatively new to the IPFire project having only really used Untangle for my corporate clients due to its ease of use for both me as an IT support person and my clients as end users of the system I install.
Welcome :)
I mentioned recently in my regular Brew Time segments that IPFire is an amazing project but the support available isn't as good as it could be and so it could put a lot of people off, both seasoned IT professionals and noobs who are going into IT pretty clueless as to what they're doing.
What made me realize that we have to do more about documentation and these things was seeing you being confused about how to install IPFire. It's not that you don't have the general knowledge about how to do things, but of course you don't have a clue *where* to start when you install IPFire for the first time.
Being not too noob-friendly is okay and to some extend I think we should not be too noob-friendly because firewalls are not for noobs. But lacking essential information for all other people who start with IPFire is not okay.
I pretty much agree with everything that Michael has said including the bits about language. I am from the UK and hence English is my native language, due to failings in the education system of the UK it is also my only language. One would assume that most residents of Germany speak English as well and so starting from English probably isn't a bad idea. But language links in with the end plan and the future for IPFire because currently the majority of your users are based in Germany and speak German and so it would make sense to write everything in German and then translate it to other languages. But if the plan is to try and expand the project to other markets internationally English would be the best language to use because it is an international language.
That's exactly the point and I don't understand all the fuzz about the language. People in America and the UK speak English. Nothing else. All the rest of Europe and the Americas and parts of Asia are used to communicate in English (at least reading). All other Open Source projects are in English. There is not a single major project I know that is not running in English.
And English is also the language for development in the IPFire project. We use it in Bugzilla, we use it on our mailing lists, we use it everywhere. The majority of the people who use IPFire is not from Germany, so there is absolutely no point in choosing any other language than English.
-Michael
Documentation mailing list Documentation@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
Documentation mailing list Documentation@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
Documentation mailing list Documentation@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
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@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
documentation@lists.ipfire.org
-
Aaron Philpott -
Bernhard Bitsch -
Erik K. -
Michael Tremer -
R. W. Rodolico