Google Season of Docs 2020
This page covers information for Google Season of Docs 2020. This includes project ideas, interested mentors and tracking of current documentation development.
For applying, see Google Season of Docs technical writer guide.
The link is added within the application and so this site shouldn't be moved to a different URL.
Project Ideas
Project 1: Documentation for OpenWrt components
The OpenWrt system is based on several core components, all developed in different code repositories. Each component has documentation that is mainly targeted at OpenWrt developers, but can also be used by “downstream projects” that use, modify and repackage OpenWrt to suit their needs. The documentation of these components is either non-existent, available as a simple README, or maintained on the OpenWrt wiki/website.
The goal of the project is to improve documentation of OpenWrt components by making it more consistent and useful:
- choose a documentation system (mkdocs, sphinx...) that will be applied consistently to all components
- transfer all documentation related to each component directly into the code repository of the component
- setup a system that builds all components documentation and makes the result easily available in a single place
- reorganize / improve each component documentation to improve consistency and readability
It is not required to have a deep technical knowledge of the components. However, in the first part of the project, the applicant will need to get familiar with the overall picture of these components.
Having both code and documentation in the same repository has two big advantages over the current approach:
- Existing developers can use the same workflow to update and review documentation as they use for code.
- New developers find latest documentation next to the code, instead of finding it on some external website.
Related material
- OpenWrt architecture (not complete)
- Technical reference pages on the wiki
Project 2: Refresh documentation for device installations
Device pages, important for users, are often very similar but still vary in steps and formulation, increasing the work of maintaining them. Also the varying structure complicates the user. A template based page generated as used by LineageOS device wiki[4] allows a consistent structure while allowing notes for special cases.
This project idea proposes to unify existing device documentations as much as possible and render them via a template engine. Ideally this reduces the work of maintaining device documentation, adding new devices and lastly make it easier to translate installation guides into multiple languages.
In collaboration with wiki maintainers popular devices should be determinded to form a page prioritization list.
Related material
- An existing proof of concept for device documentation exists https://github.com/aparcar/openwrt-devices/
Project 3: Refresh and refactor web interface documentation
The wiki offers guides on how to use the LuCI, the OpenWrt web interface, for common use cases, which is great because it's the most likely way for basic users to interact with their routers.
However this could get some extra love: Partly pictures are missing, pictures are outdated and/or missing from the web interface overview. This could be refreshed and put in nice overview, maybe even even create click-through videos.
Ideally use/create tools that automatically click things in UIs and make screenshots and thereby reproduce the documentation. This could make the documentation easily future proof and translatable.
Related material
- The existing LuCI documentation at https://openwrt.org/docs/guide-user/luci/start
Project 4: Showcase OpenWrt features and use-cases
OpenWrt has a very wide ecosystem of packages that allow many different use-cases going beyond the simple “home router” scenario.
The idea is to “showcase” several OpenWrt features and their associated use-cases, for instance by writing step-by-step tutorials with screenshots, similar to blog posts. Videos could also be produced alongside the tutorials. This is just a suggestion, other formats can be proposed.
The expected benefits for OpenWrt users are: increased awareness of OpenWrt features, easier access to various setups.
Some examples of features and use-cases to showcase:
- detailed monitoring of LAN traffic with nlbwmon or vnstat
- setting up a mobile connection (4G) as backup
- DNS filtering, similar to Pi-hole
- setting up encrypted DNS (DNS-over-TLS or DNS-over-HTTPS)
- decentralized Wi-Fi controller between several Wi-Fi access points with Dawn
- local file-sharing setup (USB disk shared with Samba/CIFS/NFS)
- VPN client/hotspot: force all LAN devices (Wi-Fi or wired) to go through a VPN
- VPN server: connect remote clients to your LAN network
- improving performance of low-end Internet connections by using SQM to avoid bufferbloat
- simple multi-WAN setup with mwan3
- advanced multi-WAN setup using MPTCP/shadowsocks or glorytun, possibly based on downstream openmptcprouter project
- run applications in LXC containers
- community mesh network using B.A.T.M.A.N.
- maintenance/upgrade ops for remote routers: make menuconfig, /files/; reverse ssh tunneling; DDNS setup; emailing log reports; backups
Related material (general)
- Why use OpenWrt (bullet-points)
- Reasons to use OpenWrt (more detailed)
Related material (technical)
- Samba documentation for file-sharing on a LAN
Project 5: Improve first-time user experience
OpenWrt can be challenging for new users: is my hardware supported? which version of OpenWrt should I use? can i use snapshots? how do I install OpenWrt? what are all these strange “apm821xx” and “ar71xx” things on the download page? how can I upgrade my router?
The idea of the project is to identify the main hurdles encountered by first-time users, and solve these hurdles to improve the first-time user experience:
- if the necessary resources already exist (e.g. Table of Hardware, quick start page), make them more visible or improve them
- if the necessary resources don't exist, create them
The proposed solution could include a “Landing page” for the OpenWrt website with the necessary information and guidance.
Related material
- See also Project 2 (for installation) and Project 3 (for basic web interface usage)