Accessibility in language
How to better document as developer for not only english speakers
- Language is important. 50% of people in Canada do not speak english. Best practice for developers how to make a documentation that is accessible for everybody (no using “jargons”, “acronym”, “gaps in documentation”)
- The better documentation explain things without assuming but tend to be longer and time consuming.
- Civic CRM. Information was findable but there was multiple place to find everything. About 5 different places to find how to do everything. There is a gap in that information is not in one single place.
- Dash is a desktop app that provide all the documentation for all the tools in multiple language. For example is you are searching to learn jQuery, this tool will bring all the documentation about it.
- Document all the steps that you have to go through. In a way that is basically connecting with the audience and do it as you speak. For example record yourself how you will do a task and then write it out.
- Couple of things that have stop a developer in the group to document is that things could change. If you are not the developer and you don’t know if the tool has been updated and documentation gets outdated.
- Documentation takes a lot of time. Documentation should be a requirement.
- Important to know is that developers assume users are english speakers. To try to make documentation multilingual.
- Training using screen sharing. Using pictures when possible. Write small sentences. Also to document within the design, forms particularly to describe the field under it.
- The location of that documentation. For example if the documentation is in a server make sure that is accessible. Using the cloud is a good idea.
- Try to read the documentation first. For example Ikea that sells a product that needs documentation to be able to put it together.
- Videos are a good thing to start the conversation. For example go into the Wordpress backend and show clients how to make edits.
- Videos are structure as about 2:00 minutes. If clients ask a question she point to the video so that the relationship is more sustainable. As oppose to just answer the questions on the moment.
- Two hours type of training. But most of the time videos work for the developer. It is good to have the video accessible because most of the time the client forget and keep calling back with the same questions.
- Where do you put the videos. Normally a page that is not part of the front end content. Using a page or section called help.
- The easiest way to do it probably using iMovie. Screenomatic is great because you can go through the process and pointing to the right things, doing the recording but also let you add overlays (audio/images). You can also add bullet points to the screens. Camtasia studio. Uber conference. Join me and Go to meeting for screen shadings. Any meeting also is a great tool. CamStudio and Open Broadcaster Software.
- Canada projects that are funded by government most be documented on both English and French. Sites that have over 100,000 views most be accessible in both languages.