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