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_i... 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@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
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_i... 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@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, i want to begin with a list of why it can be interesting to become a member in the documentation group ;-). May this can sometimes be used for a round mail or something...
- Be an important part of the development of IPFire by doing tests (quality management) of the new developed software while writing a documentation for end users. - Lern more about IPFire by documenting IPFire. - Support a good project ;-) - Know more about software which are used in this project. - Give better support to people who needs help in the forum --> become a supporter. - Learn to make a good teamwork with other people. - Extend your know-how. - Make your language skills better. - Meet new people, which are also involved by developing IPFire. - Let´s lern more about the wiki code :-\ - In that way, the project benefits also from you... ---> thats how OpenSource works.
This only as a first idea. Please change or extend this list.
Greetings
Erik
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.
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.
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.
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@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
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.
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
Hi Michael, thanks for the warm welcome.
Am 28.07.2013 um 18:27 schrieb Michael Tremer:
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.
My first idea was to find a way how the docu- and the developer group can work together to ensure that the communication flow is working. So i thought it might be an idea to illustrate this in the workflow too. But if the coordinator becomes informations about the existence of new development, may this enough too. I think also the addon developer needs also to be integrated in your above mentioned 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.
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 ?
- 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 ?
--> 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.
O.K. good idea.
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.
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
DNS Forward in english is 80 % done in point (B), as i wrote in a previous mail.
Have tried to configure my system for wireless on red but i killed the machine, hopefully that someone else can go for this....
Erik
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.
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
Documentation mailing list Documentation@lists.ipfire.org http://lists.ipfire.org/mailman/listinfo/documentation
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
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_i... 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@lists.ipfire.org mailto: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@lists.ipfire.org
-
Erik K. -
Michael Tremer -
R. W. Rodolico