Re: IPFire Wiki Workflow

[Michael Tremer <michael.tremer@ipfire.org>]

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

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

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

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

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

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

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

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

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

Put that seconds thought on the list above.

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

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

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

Please post suggestions and critics.

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

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

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

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

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

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