Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revisionBoth sides next revision
google-season-of-docs [2020/05/22 10:50] – Add project 5 zorungoogle-season-of-docs [2020/06/08 14:58] – added batman and maint/upgrade ops for remote routers steve-newcomb
Line 7: Line 7:
 ====== Project Ideas ====== ====== Project Ideas ======
  
-===== Project 1: Sub-project specific documentation =====+===== Project 1: Documentation for OpenWrt components =====
  
-OpenWrt is based on multiple sub projects, all developed in different +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 simple README, or maintained on the OpenWrt wiki/website.
-repositories. The documentation for them is mostly found in MediaWiki on +
-the OpenWrt main website. Keeping both in sync is not trivial due to very +
-tooling. This project idea propose the transfer and extension of existing +
-documentation to the sub-projects repositories. 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.+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.   * New developers find latest documentation next to the code, instead of finding it on some external website.
  
-Code documentation from the wikis technical reference would be converted to 
-Markdown format and stored in the repository. A documentation render engine 
-like `mkdocs` would be introduced to offer a webpage per project. The current 
-wiki would list those documentation websites. 
  
 === Related material === === Related material ===
  
-  * The to be individually documented projects are found on https://git.openwrt.org/. All repository starting with */project* are sub-projects of OpenWrt+  * [[commit>?a=project_list;pf=project|Git repositories of all components]] 
- +  * [[:docs:techref:architecture|OpenWrt architecture]] (not complete) 
-  * Some of the projects are already documented in the current wiki https://openwrt.org/docs/techref/start+  * [[:docs:techref:start|Technical reference pages]] on the wiki
  
 ===== Project 2: Refresh documentation for device installations ===== ===== Project 2: Refresh documentation for device installations =====
Line 93: Line 93:
   * advanced multi-WAN setup using MPTCP/shadowsocks or glorytun, possibly based on downstream openmptcprouter project   * advanced multi-WAN setup using MPTCP/shadowsocks or glorytun, possibly based on downstream openmptcprouter project
   * run applications in LXC containers   * 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 === === Related material ===
Line 102: Line 104:
   * [[docs:guide-user:services:nas:cifs.server|Samba documentation]] for file-sharing on a LAN   * [[docs:guide-user:services:nas:cifs.server|Samba documentation]] for file-sharing on a LAN
   * [[docs:guide-user:services:vpn:wireguard:start|WireGuard VPN documentation]]   * [[docs:guide-user:services:vpn:wireguard:start|WireGuard VPN documentation]]
 +  * [[https://www.open-mesh.org/projects/batman-adv/wiki/Batman-adv-openwrt-config#Batman-adv-201300-till-20190-2]]
  
 ===== Project 5: Improve first-time user experience ===== ===== Project 5: Improve first-time user experience =====
  • Last modified: 2020/06/08 17:07
  • by zorun