Bug 1204982 - Documentation update for zanata.org/help + readthedocs
Documentation update for zanata.org/help + readthedocs
Status: CLOSED CURRENTRELEASE
Product: Zanata
Classification: Community
Component: WebSite (Show other bugs)
unspecified
Unspecified Unspecified
high Severity high
: ---
: 3.7
Assigned To: Alex Eng
Zanata-QA Mailling List
: Triaged
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-03-23 19:33 EDT by Alex Eng
Modified: 2015-07-21 22:19 EDT (History)
6 users (show)

See Also:
Fixed In Version: 3.7.0-SNAPSHOT
Doc Type: Bug Fix
Doc Text:
Story Points: 3
Clone Of:
Environment:
Last Closed: 2015-07-21 22:19:41 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Alex Eng 2015-03-23 19:33:13 EDT
Description of problem:


Version-Release number of selected component (if applicable):


How reproducible:


Steps to Reproduce:
1.
2.
3.

Actual results:


Expected results:


Additional info:
Comment 1 Alex Eng 2015-03-23 19:41:33 EDT
Move and clean up documentation in zanata-server wiki to zanata.readthedocs.org.
 
The idea is to allow users/dev/maintainer can easily access to all our documentations which is currently hosted in multiple location.
Comment 2 Alex Eng 2015-03-31 01:32:33 EDT
Reorganising the documentation structure for user guides on Zanata.org/help and zanata.readthedocs.org.

- Update to latest information
- Update screen shots
Comment 3 Alex Eng 2015-03-31 19:45:31 EDT
The outline I have in mind is 

# Welcome 
Page layout explanation
- Projects
- Groups
- Languages
- Glossary
- Dashboard

User guide
1. Registration
  1.1 register to Zanata
  1.2 activate your account
  1.3 resend activation email

2. Account settings

3. Project maintainers guide
  3.1 Creating project in Zanata

    3.1.1 project settings
    3.1.2 language settings
    3.1.3 translation settings (validation and copyTrans settings)
    3.1.3 permission and roles
    3.1.4 webhook setup

  3.2 Creating new version in Zanata
    3.2.1 Copy an existing version
    3.2.2 version settings
    3.2.3 version type
    3.2.4 language settings
    3.2.5 translation settings (validation settings)
    3.2.6 Merge translations from existing version into this.

  3.3 Uploading your project

    3.3.1 Using browser
      2.3.1.1 Uploading source documents
      2.3.1.2 Uploading translations

    3.3.2 Using Zanata-Cli
      2.3.2.1 Install/setup zanata-cli for your project
      2.3.2.2 Uploading source documents
      2.3.2.3 Uploading translations

  3.4 Downloading your project
    3.4.1 Using browser
    3.4.2 Using zanata-cli
  
  3.5 Joining a group (refer to group section)

  3.6 Statistics of your project translation
    {UI statistic} and {REST API statistic}

4. Translator guide 
  4.1 Joining language team (reviewer and translation role explanation)
  4.2 Translating a document (refer to features in editor for more info)
  4.3 Reviewing translations (refer to features in editor for more info)

5. Group maintainer guide
 5.1 Creating group(need admin role)
 5.2 General Settings
 5.3 Language settings
 5.4 permission and roles
 5.5 Adding project-version

6. Language coordinator guide
  6.1 permission and roles
  6.2 Requesting new language for Zanata
  6.3 Adding team member
  6.4 Removing team member
  6.4 Update team member's role

5. Features in editor
 5.1 Layout explanation
 5.2 Editor
  5.2.1 Settings (all settings of right panel)
  5.2.2 Keyboard shortcut
  5.2.3 Concurrent editing
  5.2.4 Translation memory
    5.2.4.1 TM merge
  5.2.5 Glossary
 5.3 Project-wide search and replace
  {steps for search and replace}

6. REST API documentation
  everything in https://zanata.ci.cloudbees.com/job/zanata-api-site/site/zanata-common-api/rest-api-docs/index.html 


7. Glossary
 7.1 permission and role
 7.2 uploading glossary
 7.3 deleting glossary


8. Contacting 
  - Zanata admin
  - Language coordinator

9. TMX import/export
Comment 4 Damian Jansen 2015-04-28 19:00:38 EDT
Still more documentation to come
Comment 5 Luke Brooker 2015-04-29 00:24:03 EDT
Newer outline update:

Search
Common Questions
- All questions
- Ask a question
Guides
- Zanata Basics
  - Maintainer
  - Translators
- How to…
  - Translate a javascript project
  - Translate a HTML file in Zanata
Terminology
Accounts
Feeds
Notifications
Projects
Versions
Documents
Languages
Groups
Glossary
Search
Editor
Command Line Tools
Permissions
Statistics
Translation
Reviews
Translation Memory
Integrations
Keyboard Shortcuts
Tips & Tricks
- e.g. Jump to a user profile with search
- e.g. Get back to your last translation from the dashboard
- Should be short videos, but obvious from the title
API
- Authentication
- How to use
- Link to docs
- e.g. 
- https://stripe.com/docs/api
Administration
Installation
Contact Us
- Email
- IRC
- Mailing Lists
- Twitter
Comment 6 Michelle Kim 2015-04-29 00:24:40 EDT
1. Populate the contents for user guides 
2. Update latest information
3. Check all the links if its valid on zanata.org/help
4. Add a way for users to discover the readthedocs from zanata.org/help
5. Request for sub domain : docs.zanata.org
Comment 8 David Mason 2015-05-12 20:10:37 EDT
(In reply to Michelle Kim from comment #6)
> 1. Populate the contents for user guides
Done

> 2. Update latest information
Done

> 3. Check all the links if its valid on zanata.org/help
Not done

> 4. Add a way for users to discover the readthedocs from zanata.org/help
Not done
A link from zanata.org/help is fine until we decide whether to use a redirect.

> 5. Request for sub domain : docs.zanata.org
Done
Comment 9 Alex Eng 2015-05-13 18:06:50 EDT
> 3. Check all the links if its valid on zanata.org/help
> 4. Add a way for users to discover the readthedocs from zanata.org/help
PR: 

https://github.com/zanata/zanata.github.io/pull/21
https://github.com/zanata/zanata-server/pull/807
Comment 10 Damian Jansen 2015-05-17 18:39:44 EDT
Verified. Links are working and available from zanata.org/help
Comment 11 Michelle Kim 2015-05-17 19:13:19 EDT
Hi, 

Thanks for adding the links to readthedocs from zanata.org/help is working.

However, I did random test of the broken link from zanata.org/help and the link seems still broken as follows:

From this page, http://zanata.org/help/create-project/

"There is a brief description for each project type next to each project type option. If the description is insufficient, more information on each project type is available at Project Types help page."

When I click the link to Project Types Help Page, below link shows up with following messages:
http://zanata.readthedocs.org/en/latest/user-guide/project-types/


You've found something that doesn't exist.

What are you looking for?

Go to the top of the documentation.


        \          SORRY            /
         \                         /
          \    This page does     /
           ]   not exist yet.    [    ,'|
           ]                     [   /  |
           ]___               ___[ ,'   |
           ]  ]\             /[  [ |:   |
           ]  ] \           / [  [ |:   |
           ]  ]  ]         [  [  [ |:   |
           ]  ]  ]__     __[  [  [ |:   |
           ]  ]  ] ]\ _ /[ [  [  [ |:   |
           ]  ]  ] ] (#) [ [  [  [ :===='
           ]  ]  ]_].nHn.[_[  [  [
           ]  ]  ]  HHHHH. [  [  [
           ]  ] /   `HH("N  \ [  [
           ]__]/     HHH  "  \[__[
           ]         NNN         [
           ]         N/"         [
           ]         N H         [
          /          N            \
         /           q,            \
        /                           \



I would like to request thorough check of the broken links again from zanata.org/help 

Thanks,
Michelle
Comment 12 Michelle Kim 2015-05-17 19:15:52 EDT
I checked directly from the readthedocs page and it seems the valid link is 

http://zanata.readthedocs.org/en/latest/user-guide/projects/project-types/

However the zanata.org/help page redirects it to 

http://zanata.readthedocs.org/en/latest/user-guide/project-types/



So the redirect link from zanata.org/help page : 

http://zanata.readthedocs.org/en/latest/user-guide/project-types/ should be changed to 
http://zanata.readthedocs.org/en/latest/user-guide/projects/project-types/
Comment 13 Michelle Kim 2015-05-17 19:19:04 EDT
Another broken link I just found:

From this page, 
http://zanata.org/help/cli-configuration/

You can customize zanata.xml with command hooks so that other tools will automatically run before or after Zanata commands. Read about command hooks at the command hook page on the wiki.

Command hook page on the wiki is no longer valid :

https://github.com/zanata/zanata-server/wiki/Client-Command-Hooks
Comment 14 Michelle Kim 2015-05-17 19:20:53 EDT
Since we have most up-to-date information on readthedocs, we should find a way to redirect the zanata.org/help contents to the new docs site in the near future.
Comment 15 Alex Eng 2015-05-17 19:28:11 EDT
Michelle, 

Thanks for checking the links. 



PR for broken link:
https://github.com/zanata/zanata.github.io/pull/24
Comment 16 Damian Jansen 2015-05-18 20:51:03 EDT
Verified (multiple commits/repos)

Note You need to log in before you can comment on or make changes to this bug.