@lidialab and I have been working together on the Polyglots Handbook reorganization effort. The goal is to propose a new order of the Handbook that will, hopefully, improve the user experience and to update any pages that may be out-of-date or missing.
To begin, we identified five different “user types” to identify the types of people who might use the Handbook. Those were:
- Individual/new translation contributors
- Editors (General Translation Editors and Project Translation Editors)
- Locale managers
- Polyglots Global Mentors
- Developers (theme and plugin authors)
We decided to approach the changes by identifying which pages in the Handbook were related to which user type. If you’re curious, you can see how we did that in our Google Doc here.
Proposed reorganization
At this point, we’ve come up with an outline for the proposed new order of the Handbook pages. There are a few new pages that we will need to write, and all the existing pages would benefit from having someone review them for any updates or improvements. Here’s what we propose for the new outline:
Call for feedback and volunteers
For next steps, we’d like to:
- Ask for any feedback on the proposed reorganization of the Handbook. Have we missed any user groups? Would one page fit in a better section? Would a section benefit from a new page?
- Simultaneously, we would like to open a call for volunteers to help with reviewing and writing documentation. (We will post more information below.)
- Once all the documents have been reviewed and updated, we will add and publish any changes live on the site.*
Our target deadline is June 30th, 2020, which will give us an entire month for feedback and volunteers. At the end of the deadline, we will post an update and revisit next steps.
How to Help
If you’re interested in helping, we’ve created this spreadsheet for volunteers to sign up. Please type your WordPress.org username next to the page you would like to work on.
- To edit existing pages, please copy the content into a Google doc. Add your Google doc to the Polyglots Handbook folder (ping @lidialab or @evarlese if you need access). Then, use the Suggesting mode to make edits/changes so it is easier to track changes.
- For new pages, please write them in a new Google doc and save to the Polyglots Handbook folder.
WCEU Contributor Day is June 4th (don’t forget to register if you haven’t already!) and we would love for anyone to work on this during that time. If you are new to Polyglots, support Polyglots but don’t speak another language, or if you would like to contribute to Polyglots in a new way, we would appreciate your help. Both during contributor day, and before or after Contributor Day!
* As a note: while we will change the order of the Handbook, we also want to maintain the permalinks for each page as much as possible. (Props Lidia for thinking of this!) Before publishing new pages, we will need to set up redirects so that links to the old URLs continue to work seamlessly.
A huge thanks to @evarlese that do the principal and super job to get this activity starting with a good plan. When I’ve seen the reorganization project task, I thought It was really needed especially for new contributors sections, and I joined!
I’ve added only a limited point of view. Now we need the help of all of us to collect a lot of suggestions on how to going on to make it a very good Handbook!
Thanks so much for your kind words, Lidia – I couldn’t have done it without you 😀
Hi @evarlese, thanks a lot for this proposal. Please add me to your list of ‘reviewers’ any time. E anche grazie @lidialab 😉
I would say that the defined user groups are perfect.
The ‘Team o2’ seems on it’s own, so I hope we can slide it inside e.g. Setting up your local site.
One thing for the reorganization: Please make sure not to change any slugs (permalinks) of the pages as you never know where they have been referenced from.
Thank you so much @casiepa – that will be wonderful!
Good suggestion, I agree – I think it does make more sense there 😀 For the slugs, that is definitely something we want to be careful of!
Off hand, do you know if it is a possibility to maintain the permalink structure if we change the location of the page? (If not, we will double-check the steps for this before making any changes live in the Handbook that might affect this.)
It’s always a good idea to keep a record of the original permalink to be sure, but if I remember well, moving a page to another parent is keeping the permalink. So you SHOULD be fine.
That’s helpful, thank you Pascal!
Note/update: If you have a comment or change you want to make to one of the Handbook pages, but do not want to sign up to edit the entire page, please add your comment in the Notes section on this spreadsheet. Then, the person who does sign up to edit that page can include your comment in their changes.