Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation on team projects #725

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Update documentation on team projects #725

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 55 additions & 14 deletions doc_src/en/HowTo_SetUpTeamProject.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,9 @@
</note>

<para>The local repository is used to add the initial project to the
server, and can also be used for maintenance tasks, such as deleting
files, that cannot be performed directly within OmegaT.</para>
server, as well as for certain maintenance tasks. See the
<link linkend="how.to.manage.team.project"
endterm="how.to.manage.team.project.title"/> section for details.</para>
<para>We recommend that you avoid using that folder for translation
tasks. If you need to perform translation or review tasks on that
project, use OmegaT to download a separate copy of the team project and
Expand Down Expand Up @@ -102,7 +103,7 @@
to the repository. Use <link endterm="menus.project.title"
linkend="menus.project"/><link
linkend="menus.project.commit.source.files"
endterm="menus.project.commit.source.files.title"/> to add files
endterm="menus.project.commit.source.files.title"/> to add source files
from OmegaT.</para>

<para>You must use your SVN or Git client, or the command line, to
Expand All @@ -127,7 +128,7 @@
linkend="menus.project.commit.target.files"
endterm="menus.project.commit.target.files.title"/>.</para>

<para>The team project administrator must use the local VCS to
<para>The team project manager must use the local VCS to
<emphasis role="bold">modify</emphasis> or <emphasis
role="bold">delete</emphasis> those files. Some plugins can make this
task easier. See the <link linkend="dialogs.preferences.plugins"
Expand Down Expand Up @@ -164,7 +165,7 @@
</note>

<para>After the project is ready and has been uploaded to the server,
the team project administrator has to set up access for the translators.
the team project manager has to set up access for the translators.
Accessing a team project requires the following information:</para>

<orderedlist>
Expand All @@ -173,9 +174,9 @@

<para>The translators will have to create an account for the
service, and send their user name to the team project
administrator.</para>
manager.</para>

<para>The administrator will then grant write access to the
<para>The manager will then grant write access to the
repository to those accounts.</para>
</listitem>

Expand All @@ -184,10 +185,10 @@

<para>If the server is self-hosted and does not have a provision
for translators to register an account themselves, the team project
administrator must create accounts with write access for the
manager must create accounts with write access for the
translators.</para>

<para>After creating the accounts, the administrator must send the
<para>After creating the accounts, the project manager must send the
translators their individual credentials.</para>
</listitem>
</orderedlist>
Expand All @@ -197,7 +198,7 @@
<para id="how.to.setup.team.project.have.members.download.title">Have
everybody download the project from OmegaT</para>

<para>Administrators have two options for sending the location of the
<para>Project managers have two options for sending the location of the
project to the translators:</para>

<orderedlist>
Expand All @@ -219,10 +220,10 @@
</listitem>
</orderedlist>

<para>After the team project administrator confirms that a translator
<para>After the team project manager confirms that a translator
has been able to open the team project, it is a good idea to make sure
that the <link linkend="menus.tools.statistics">project
statistics</link> are the same for both the administrator (on the
statistics</link> are the same for both the project manager (on the
server) and the translator (locally).</para>

<para>If they do not match, make sure the
Expand All @@ -243,6 +244,46 @@
</orderedlist>
</section>

<section id="how.to.manage.team.project">
<title id="how.to.manage.team.project.title">Manage a team project</title>

<para>Team projects involve a number of management tasks not directly related
to translation. Project managers may find it advantageous—or even necessary—to
handle such tasks directly from the VCS repository, particularly in cases where
the project manager only acts as a coordinator and is not involved in the translation
process itself.</para>
<variablelist>
<varlistentry>
<term>Deleting files</term>
<listitem>
<para>OmegaT does not provide a mechanism to delete files from a team project.
If any shared team project files have become unnecessary, the project manager
<emphasis>must</emphasis> delete them from the VCS repository.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Adding files</term>
<listitem>
<para>Although OmegaT provides a mechanism for adding translation source and
target files to the repository, the project manager must add any other files,
such as dictionaries, glossaries or reference translation memories, from the
VCS repository.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Checking project statistics</term>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why "checking" and not "Consulting"?

<listitem>
<para>This only applies to workflows that ask translators to commit the translated
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because that's essentially the way the feature request and the implementation work. Statistics are only committed when target files are committed.

I'll have to expand on that more, though. Maybe add a short section on the difference between managing projects as:

  • one of the translators involved, with a copy of the project on their system
  • purely a coordinator not involved in the actual translating, and working directly with the repository and without a copy of the OmegaT project on their system.

target files to the repository as deliverables.</para>
<para>When OmegaT commits the target files, it also commits the project statistics
in <filename>.txt</filename> and <filename>.json</filename> format. This enable the
project manager to consult the statistics, and possibly automate their processing,
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why ? How ? Even if it is outside the scope of OmegaT, maybe clarifying a bit could help?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right. I haven't had as much time as I'd like, but I'll try to rework the section to expand and clarify on things sometime over the next week.

without the need to open OmegaT.</para>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that necessary ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which part? The file types, or the part about the project managers looking at the statistics and automating their processing?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The second part. I think burying a possible use at the end of a sentence is the best way to never have it used. Maybe having a small section about automatic processing of OmegaT data in the stats and linking to this section is best.

</listitem>
</varlistentry>
</variablelist>
</section>

<section id="how.to.setup.team.project.mapping.parameters">
<title id="how.to.setup.team.project.mapping.parameters.title">Repository
mappings</title>
Expand Down Expand Up @@ -405,7 +446,7 @@
sharing</title>

<para>The above process describes the most common scenario, in which the
team project administrator has full control of the project and all files
team project manager has full control of the project and all files
(and statistics) are identical in all instances of the project, both on the
server and the local systems of the translators.</para>

Expand All @@ -414,7 +455,7 @@
subset of the other files.</para>

<para>The basic procedure is essentially the same, except that the team
project administrator does not add every file to the version-controlled
project manager does not add every file to the version-controlled
project on the server. The remaining files are either copied by the
translators themselves, or mappings that synchronize files from other
locations are defined.</para>
Expand Down
17 changes: 9 additions & 8 deletions doc_src/en/HowTo_UseTeamProject.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<para>Team projects use synchronization mechanisms between project members.</para>

<para>Once a OmegaT team project is installed on a server, the administrator
<para>Once a OmegaT team project is installed on a server, the project manager
sends members the information they need to access it: a URL indicating the
location of the project, or an <filename>omegat.project</filename>
file.</para>
Expand Down Expand Up @@ -46,11 +46,11 @@
linkend="menus.project.download.team.project"/> to bring up the
<guilabel>Download Team Project</guilabel> dialog.</para>

<para>Enter the URL provided by the team project administrator in the
<para>Enter the URL provided by the team project manager in the
<guilabel>Repository URL:</guilabel> field at the top of the dialog,
and specify a folder for the project in the <guilabel>New Local
Project Folder:</guilabel> field. Leave the <guilabel>Default
branch</guilabel> option checked unless the project administrator
branch</guilabel> option checked unless the project manager
has provided instructions for using a custom branch.</para>
</listitem>

Expand Down Expand Up @@ -141,7 +141,7 @@

<para>In a team project, the basic configuration parameters of the
local project are always overridden by the configuration on the
server originally set by the project administrator.</para>
server originally set by the project manager.</para>
</listitem>

<listitem>
Expand Down Expand Up @@ -179,7 +179,7 @@
<listitem>
<para>If you first download the remote project using an
<filename>omegat.project</filename> file provided by the project
administrator, OmegaT will use the mappings in that file, if
manager, OmegaT will use the mappings in that file, if
any.</para>
</listitem>

Expand Down Expand Up @@ -208,7 +208,7 @@

<listitem>
<warning>
<para>Only the project administrator should use <link
<para>Only the project manager should use <link
endterm="menus.project.title" linkend="menus.project"/><link
endterm="menus.project.commit.source.files.title"
linkend="menus.project.commit.source.files"/>.</para>
Expand All @@ -225,7 +225,8 @@
linkend="menus.project"/><link
endterm="menus.project.commit.target.files.title"
linkend="menus.project.commit.target.files"/> to add them to the
server, if the project administrator has requested you to do so.</para>
server, if the project manager has requested you to do so.
Committing the target files also uploads the statistics files to the server.</para>
</listitem>
</varlistentry>

Expand All @@ -236,7 +237,7 @@
<para>Files in a team project cannot be deleted from OmegaT or the local
file system. They will be restored the next time the project is
synchronized. This task is normally performed by the project
administrator.</para>
manager.</para>
</listitem>
</varlistentry>

Expand Down
Loading