From mboxrd@z Thu Jan 1 00:00:00 1970 From: embp To: documentation@lists.ipfire.org Subject: Re: IPFire Wiki Workflow Date: Fri, 12 Jul 2013 14:06:22 +0200 Message-ID: <2A3A262F-75BA-4C69-8670-16C8ABB5ACE1@web.de> In-Reply-To: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="===============7722688282679659387==" List-Id: --===============7722688282679659387== Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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? >=20 > for myself this questions are difficult to replay, haven=C2=B4t 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 whi= ch 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 star= ted to translate wiki sections from german to english and tested also a vario= us amount of addons and functions on the basic system of IPFire.=20 > I think also what Rod says is important, new users or mostly people from th= e forum feels a high obstacle to change things in the wiki cause they think t= hey 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 a= ttitudes, but we have tried also those rudiments with sides like this --> htt= p://wiki.ipfire.org/projects/docs/start and references to this side in the wi= ki, but also by motivating the people directly in the forum. The result is th= e reason of this mailinglist theme, so i have not really an answer how we can= attract people to work more in this topic. >=20 > 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 fo= rum can be informed in that way. But i don=C2=B4t know how much attraction co= mes out of that. >=20 > The decision what to work on should be set by a similar priority like in de= velopment. 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 th= at the wiki for the basic system is more important to have it complete and we= ll 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) wa= s explained, the questions concerning to the proxy in the forum was reduced d= ramatically. Also the possibility to give short help informations only by lin= king to the specific section was a work simplification for supporter in the f= orum. >=20 > 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 availabl= e, this takes me back to the question "How do we attract people". >=20 > "For How long?": Depends on the theme and also on the amount of helpers i t= hink. >=20 >> 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? >=20 >> 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. >=20 > Not only You Arne and Stevee should follow those rules, also addon develope= rs, or development in general. Sorry for the worse link to Wikipedia --> http= s://en.wikipedia.org/wiki/Software_documentation#Role_of_documentation_in_sof= tware_development but i think in there are some good statements why documenta= tion in software development are very important and also a inherent part of d= evelopment. If it is in german or in english is for now secondary i think. Al= l 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 docu= mentation 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=C2=B4t be a whitewash for incompleteness.=20 >=20 > So an idea can be to have an closer contact from the developer team to a po= ssible documentation team, to ensure this knowledge transfer. This can also b= e attractive for new helpers to stay a little closer to the matter. >=20 >=20 > Erik >=20 >=20 >=20 > Am 12.07.2013 um 00:01 schrieb Michael Tremer: >=20 >> 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). >>=20 >> 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). >>=20 >> Central questions are: >>=20 >> * 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? >>=20 >> The has to be a "team", otherwise we don't need to think about the >> content. >>=20 >> 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? >>=20 >> 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. >>=20 >> -Michael >>=20 >> 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 h= ave tried a more compressed layout of the configuration wiki. The actual (off= icial) look of this section can be found in here --> http://wiki.ipfire.org/e= n/configuration/start .=20 >>> The new one is very unready and only a first try, but it should show an i= dea how it could be better overviewed.=20 >>> In here --> http://wiki.ipfire.org/en/configuration/start you belong to t= he new structure. >>> Until now there is no content behind the structure but this should be don= e fast by a copy and paste of the old content. <-- Better to check out some s= ections 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 ). >>>=20 >>> A statement to the wiki workflow: >>> In the last months, mostly work was done in particular articles of the wi= ki, also to clean up the code cause a lot of plugins was replaced, so the gen= eral structure wasn=C2=B4t 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 fi= nd out the worse sections to make them better and clearer. >>> * If old articles will be revised, the explained functions should also b= e 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" hav= e it easier. >>>=20 >>> Also to overview the actual changes in the wiki needs to be checked. In h= ere --> http://wiki.ipfire.org/start?do=3Drecent a done list can be overviewe= d. 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. >>>=20 >>> 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 befor= e. 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 s= omeone can go for corrections (also in german). Sometimes this kind of workfl= ow did it very good (thanks again Rod by the way ;-), but sometimes (especial= ly in the last past months) there was no response. As time goes by the wiki a= rticles leaves the memory that there was something to do and they where forgo= tten. So it is maybe an idea to mark those articles as "uncheck, everybody is= invited to go for a revise" or something. >>>=20 >>> So for the first some ideas from me. >>>=20 >>>=20 >>> Greetings=20 >>>=20 >>>=20 >>> Erik >>> _______________________________________________ >>> Documentation mailing list >>> Documentation(a)lists.ipfire.org >>> http://lists.ipfire.org/mailman/listinfo/documentation >>=20 >>=20 >=20 --===============7722688282679659387==--