docs - approving revisions - how / why?


#1

Hi,
I did some changes lately to several docs.
But they are still not “approved”.
When I was contributing to Synfig doc that last time there was nothing like that in place.

How does the approving process work?
(Who decides, when, based on what…?)

Why do we have that?
No such thing needed for Wikipedia, why do we have it?
Isn’t that unnecessary additional work for someone to check all changes first,
while we struggle to have enough contributers…

I like to contribute, but I do’t like to be ruled too much, where not needed…
I work in a way where I discuss general changes in this forum before I do them
and I try to follow all rules that have been documented in the writers’ guide.
I have seen all others working the same way…

I fear that holding back changes is (in the long run) going to frustrate and
keep people away from contributing…


#2

Certainly, I must agree with that.

-G


#3

I am the person responsible for approval. And I have a limited time.
More than that, as soon as we start the sprint for updating docs for the new terms - no pages will be approved until we finish it.

There IS such thing in Wikipedia (at least in Russian one, see the top of this page for example - http://ru.wikipedia.org/wiki/Deep_Fritz. Don’t know if they going to adapt the same approach for English though…).

WE need that for 2 reasons:

  1. That way we can work on documentation for the upcoming version “at the background”. I.e., we are working on documenting new functions, but since those functions are not released yet - they are not visible. As soon as the new version is released - then all pages are approved and become visible for general audience.

  2. The approval is made to prevent undesirable changes. As an administrator I prefer to shape the documentation into particular direction. Unfortunately, due to my limited time I have not much time to work on docs last months, and that’s my fault for sure. But my resources are limited. There are lot of other things to do here that needs my attention.

If you don’t like something then you have 2 choices:

  1. Fork your own doc project and write whatever you like.
  2. Ask me to leave the doc administrator position and I will leave with no problem. Then I will be happy to fork into my own doc project.
    At the end - this is an opensource, right? and if you don’t like someone’s work - just do it better. :slight_smile:

#4

Konstantin…
calm down, I didn’t meant to say you’re doing anything wrong here…
No time to comment now, will do later today… sorry.


#5

I do some in the wiki/doc since little months…
Has i remember… when i started it was like you say Oho : no approval. And that, suddenly (for me), change.

Zel, YOU are preparing a sprint. This is the third time url=https://forums.synfig.org/t/and-what-about-a-synfig-floss-manuals/2034/2[/url] url=https://forums.synfig.org/t/please-add-hints-to-bugs-that-need-urgent-fixes-here/850/23[/url] i read you about this sprint “community” doc project. You know me interrest about that. Could be opensource spirit that you open this source, because th[ur=http://10.creativecommons.org/l]at[/url], is not just about forks.

Nota; Zelgadis, you have wrote a severe message i think.

:::: Nota Bis ::::
HAppy Bithday #10 CC !!!


#6

I know that it is hard work administrating anything, be it a wiki or a forum! :slight_smile:

But I mean no offence is asking, why is the approval set “on”? Blocking vandals takes WAY WAY less time than monitoring every change.

In ACTUAL numbers there are 2-3 eager people helping to edit the wiki. No need to act like we are protecting Rome from the barbarians. If a problem happens it will be small. No one can delete old versions of pages and I don’t expect much vandalism in a doc with so few readers.

Just IMHO… I hear one person wanting to edit and another person tired of the work involved in stopping that first person from editing. Hardly seem a good way to spend time that could be spent making animations! :slight_smile:

Good work to all!


#7

well, finally I found some time now to post a bit longer answer to Zelgadis’ statements…

As I said, I didn’t want to say anything is wrong in general today.
I am never interested in fingerpointing and understand that all people here are volunteers and are having restrictions in time they might spend.

I do understand the first reason: such a function (to hold back new versions) is needed for preparing for new releases.
Actually I appreciate that we have the chance to do that compared to former times (I think I asked for a function like that myself few years ago…)

On the other hand I just wanted to give you some feedback on how it feels for someone contributing, when a change is not displayed within a short timeframe.
And I wanted to discuss whether or not there is a chance to change something about that.

As for the second reason I would like to call it “Quality Control” (QC)…

QC is definitively a good thing to do, but QC doesn’t come for free, it always binds resources (for reviewing and approving) and it contains a hierarchy thinking (“reviewers know better”),
that has to be handled in a very sensitive way if you have a volunteer situation (I think you know what I mean…).

Additionally, if there are severe time restrictions on the reviewer’s side, then opening a process to less control is a possible option, that gives the reviewer a bit more time while opening the risk of less quality, of course.

As a way in the middle maybe…
we can have clear messages on a timeframe such as “once per week” or “twice per month”.
As soon as there is a fixed date/time for doc changes to be reviewed, discussed and (maybe) approved, then it is much easier to wait for this from a contributor’s point of view.

Hope this helps to understand the reason why I started this topic.
I am open to try out things over time… to find the best way for us all as a team.

OHo.

BTW: creating forks is, at least in my eyes, the worst thing to do. Instead I would prefer to leave and shut up.


#8

First of all, my apologies for my previous post - I’m a bit overreacted here.

Let me explain.

We are in the process of preparing the release of new version of Synfig. And after a long discussion it was decided that many things will have different names in new version (new terminology). For example, we will have “Control Point” instead of “Duck”, etc.
The question was how to properly update documentation.

We could release a new version and update the documentation AFTER that. But as everyone is volunteers here, tupdating documentation could take a long time and having documentation with outdated terminology surely brings a lot of confusion.

It is also possible to update the docs BEFORE the release, but then we will have same confusions during the updating process.

That’s why it was decided to introduce the revision approval. So we can start documentation sprint (updating docs for new terminology) before release, but keep our changes unapproved. So while we are working people will see the documentation with old terminology. But when everything will be properly rewritten we will release new version of Synfig studio and approve everything.

I don’t plan to do documentation terminology rewrite alone. I will need your help. But to coordinate many people working on the updating at once I need to develop strategy, algorithms and write clear instructions how we do that together. That takes time. That’s why I’m always talking about doc sprint but haven’t started anything yet.

QC is also was the reason, but looks like I cannot handle it here at the moment. So, if Oho or Djay would like to give us a hand and get those responsibilities I will be happy to grant them all required permissions.


#9

Sounds reasonable, fully understood & no problem :slight_smile:

Can we help with thoughts about how to organize?
I do have some ideas about that in case you’re interested.

Will we have a approval run before we start with the renaming?

As for the approver job I’d prefer to have someone

  • very familiar w/ Synfig / Synfig Studio
  • AND native english speaker.

But if this is how I can help you and noone else fulfilling the prereqs above is volunteering for it,
then tell me about the details and I’ll let you know whether I can do it.


#10

Thank’s for the propo, but i’m not fully english compliant to do some QualityCertif on the original english doc. Even if i ‘love’ do maniac task like formal syntax / unification… oho … are you ready ? Maybe with some extra help (native english/synfig experimented user) during the doc/sprint season ?

see(:ya!


#11

d.j.a.y,
my english is okay, but I’m not a native speaker.

I might help if noone with better prereqs is willing to do it.
And I’d like to learn about the expectations from the core team (at least Zelgadis & Genete) before I decide, whether or not I can do that.

Sure, help always appreciated! :slight_smile: And this would make it a bit easier to say yes… for me


#12

When I started to write wiki pages four years ago, I had the same bad English than now. Also my knowledge of Synfig was partial and I was just writing about what I learned.

I think that it is fine that someone no native English can approve master wiki pages. Just keep in mind that when you doubt, you can use the talk section of the wiki to discuss the issue or the usual development channels (this forum or the documentation mailing lists).

Pages are not static and are under continuous revision. If later a native English speaker finds a better sentence to express the same idea it will be changed.

-G


#13

I agree with Genete.

Also, Djay can take the approval rights too for the purpose to approve French pages, since he is translating them anyway. Also that will allow him to approve formal revisions ( like adding “shortcuts” and “literal” templates).

I have posted a draft post for Terminology Rewrite sprint - viewtopic.php?f=25&t=4056
Please don’t rush to edit anything for now, because we’re still testing the latest ui to ensure all the strings are correct and fit properly.


#14

And i’ts a chance (?) for us, by screen/keyboard medium we does’t have the pleasure of your native accent :open_mouth:

Ok, no more… you convicted me :wink:

i’ll revised my own transaltion, and, if i understand/approve the pieces of english you (g) have puted in the doc, everybody with some basics in english will also… !

see(:ya!


#15

Guys,

I’ll be on a business trip to the US for 10 days starting next Monday,
I might have some time restrictions on working on Synfig doc topics during that time.

With d.j.a.y helping for French translations and wiki engine / template specifics.
Genete and Zelgadis and others from the team still around for the wiki engine, website, Spanish, Russian, Synfig expert knowledge, …

… I’ll give it a try!
Let’s go for it!

some initial questions:

  • Can you disclose the schedule for the new version that needs the renaming sprint? Just to get a feeling for the timeframes.
  • Will you have a small doc to explain how the approval fuctions are working?
  • Will you update to new version of the wiki engine/scripts before that as we experienced some problems with the lastest doc vs. preview?

#16

Oho and Djay, you are now members of Sysops (Administrators) group at the wiki. Besides the approving pages that will give you additional powers like deleting and restoring pages. Use those powers wisely.

How the approval works:

  1. You can set any version of page as approved by going to the History tab (there is such one at the top of each page).
  2. Also, there is a special page available http://wiki.synfig.org/wiki/Special:ApprovedRevs where you can see the list of approved/unapproved pages and the pages whose approved revision is not their latest.

I cannot say anything clear about that. There is still ongoing discussion about the changes in the “terminology rework” branch. I have to wait when everything will settle down, then I will build the testing binaries so everyone can use them for reference during the doc sprint.
I think that’s important to have everything settled before starting sprint.

I will try to fix the problem, but I’m not sure how much time that will take. I’m not sure update will solve that problem and then I will need to dig deeper for the problem roots. So I can’t promise anything. Still, I think it’s OK to start the doc sprint when issue isn’t fixed, as long as all participants aware about this issue.


#17

sure!

Thx a lot!

Is it possible to tell us about a very rough timeframe, like "within 6 months, 12 months… "?


#18

Here is how I see the schedule for the next release (without times):

  1. First there must be a stable version of the code at the repository. Currently the first test of the renaming is being held by Zelgadis (and by me) and some bugs has been found that are being fixed by Jcome.
  2. When that happens it means that the renaming is ready from the point of view of the code and then it comes the rest of things (wiki and review of rest of translatable strings that might refer to renamed items) ## this is the point of the wiki rename sprint start.
    2-bis) At this point the translatable strings should be ready and then the new po files should be generated and send to transifex. A call for translations and update of the new strings should be made here.
  3. In parallel I’ll continue reviewing the branches that will be merged to the stable one, once they pass the tests. Once there aren’t branches pending to be merged the code is ready for the rest of steps of the release.
    3-bis) If I find more new translatable strings with the incoming branches they must be updated at transifex too.
  4. Zelgadis would add the needed commits to update: splash, version, updated po files from transifex, news, legal and copyright files. Once reached the updates there will be the release commit.
  5. Different package maintainers would build the packages and then they are sent to Sourceforge. ## At this point the wiki should be ready to be released with the new version after the renaming.

This time the new version will be 0.63.06 since there are nice additions or bug fixings, there isn’t anything that justify a increase in the second version number.

The time between end of point 2 to end of point 5 is not well defined and depends on how much quick do we Zelgadis and I work together in the release procedure. Typically the length between the strings freeze (end of point 2) to official release day (end of point 5) is about one month.

Additional help is needed for the Transifex tasks. I think that Jcome has helped on that previously.

Release procedure is written on the dev area of the wiki but this time it is a bit special for the renaming thing.

Any help is welcome but we understand that get the inertia of the release procedure is not easy when you need to have lot of passwords, admin rights and dedicated environment to make everything work. So for the moment, the help is needed at the wiki area, the transifex area and of course all the post release actions.

I think that Zelgadis should post a task-list with owner soon, here in the forum, like I have done in the past releases. It would help to have a better overview of all the steps.

Cheers
-G


#19

Okay, that sounds like 2-4 months from now … detailed enough for the moment.
Means for doc approvals:
we will go forward with short term doc approvals until we reach step 2.
After step 2 we should then use the approval features for preparing for the new release (as Z. said before already).


#20

Thank’s both for sharing here details of the plan (as i don’t read to much synfig-dev list)

I’lll try to don’t approve “my” english revisions and also, not use too much the mass deletion special page (or with care :wink:

Oho, did you saw?, new terminology is comming ! (library panel)

see(:ya!