Documentation

documentation@lists.ipfire.org

226 discussions

Re:New configuration wiki site
by Luke Lawry 03 Aug '13

03 Aug '13

Here goes my first email to this group. @Erik K. This change certainly looks cleaner and less cluttered than the old one. One thing that I would change is the description of the different options. For example, "System" is described as "What is under the System Tab can be found here." (english translation) Why not use the old description of "Here you will find basic settings that affect the IPFire itself." which seems less redundant. Putting the description on the first page will keep people from having to click on things in order to see what's inside. If you have an english version I would like to take a look at it and maybe add some stuff. Greetings, Luke -----

2 1

Translation of the wireless addon page
by Luke Lawry 03 Aug '13

03 Aug '13

The english wiki page for the hostapd addon has recently gone through a major rewrite and needs to be translated. See it here: http://wiki.ipfire.org/en/addons/wireless/start Greetings, Luke -----

2 1

IPFire 2.13 Core Update 71 documentation
by Michael Tremer 02 Aug '13

02 Aug '13

Hello, we are going to release the next Core Update on Monday or Tuesday, if everything goes well. The changelog is over here: http://planet.ipfire.org/post/ipfire-2-13-core-update-71-in-testing As you can see, there is a lot of new functionality that needs documentation. I also pointed that out in the last paragraph of that post. As Erik had some problems with setting up his testing box, he asked me to do the wireless client documentation, which can be found here: http://wiki.ipfire.org/en/configuration/system/wlanclient This is a more elaborated version of developer documentation you guys will get from us developers. @Coordinator: Please add this to the list of things that need to be done. I would also point out that there are some other changes that should be updated in the documentation. Are you guys able to figure that out on your own or do you want a list of what has changed? Best, -Michael

1 0

Re: IPFire Wiki Workflow
by Erik K. 02 Aug '13

02 Aug '13

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

3 8

New configuration wiki site
by Erik K. 01 Aug '13

01 Aug '13

Hi all, to give a better overview of the wiki sections, i tried to reduce the configuration site of the IPFire wiki. So there wasn´t changed some content, this example is also in german but it should give an idea of a new more compressed structure. In here --> http://wiki.ipfire.org/nonpublic/de/configuration/start you can find the new one. To compare it, in here you can find the actual one --> http://wiki.ipfire.org/de/configuration/start It might me nice if you can give some input an ideas to it. Greetings Erik

1 0

New DNS-forwarding wiki
by Erik K. 29 Jul '13

29 Jul '13

Dear documentation team, i want to introduce the DNS-forwarding wiki http://wiki.ipfire.org/en/configuration/network/dnsforward which was extended and is currently on stage (B) of the new wiki workflow --> http://wiki.ipfire.org/projects/docs/workflow . If you think the point "(B) Authoring the article in English" lacks, please go for enhancements. Otherwise point (C) can be worked out. Greetings Erik

2 2

IPFire Wiki Workflow
by Michael Tremer 27 Jul '13

27 Jul '13

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

5 18

DMZ server with multiple names.
by Ralph Crongeyer 16 Jul '13

16 Jul '13

Hello list, I have a web server with multiple eg (servername.mydomain.com, www.mydoman.com, mail.mydomain.com, webmail.mydomain.com, vpn.mydomain.cometc...) and I would like to be able to access these by name from my Blue network. I have DMZ pinholes and I can get to the server by IP just fine but IPFire dosn't know about the other names. Can I add multiple names to an IP from IPFire? If so where do I do this in the GUI? I would like to do this so I don't have to run bind on my web server and use it for DNS lookups. Thanks, Ralph

1 1

Re: IPFire Wiki Workflow
by embp 12 Jul '13

12 Jul '13

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

1 0

Please could someone review it
by Daniel Weismüller 09 Jul '13

09 Jul '13

http://wiki.ipfire.org/de/updates/openvpn-transfer-net-block http://wiki.ipfire.org/en/updates/openvpn-transfer-net-block All suggestions are welcome. - Daniel

3 3

← Newer
1
...
8
9
10
11
12
13
14
...
23
Older →

Jump to page:

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

Documentation