[OpenWrt-Devel] Applying to Season of Docs

[Paul Spooren]

On Sun, 2020-05-03 at 17:37 +0200, Hauke Mehrtens wrote:
> On 5/1/20 11:07 PM, Paul Spooren wrote:
> > Hi all,
> > 
> > Google offers a program[0] to stipend people writing technical documentation
> > for
> > open source projects. The stipend is possible for anyone 18+ and not living
> > in a
> > US embargoed country, so unlike the Google Summer of Code project not only
> > for
> > students. Successful writers get a stipend of about $6000, mentors $500,
> > from my
> > understanding these stipends are at least in some parts of the world tax
> > free.
> > 
> > So much about the program, question is how OpenWrt could benefit from it. 
> > 
> > * Some time ago there where some ideas on IRC to add development information
> > to
> > OpenWrt specific tools instead of managing it in the MediaWiki. Articles
> > from
> > docs/techref[1] could be updated, cleaned and ported to the project
> > repositories. For example, move the ubus network docs[2] directly to the
> > netifd
> > repository[3] so developers can update it conveniently when adding new
> > features.
> > The existing wiki would then point to an online rendered version of such
> > docs.
> > Using a tool like mkdocs(.org) allows to create documentation websites based
> > on
> > Markdown with minimal dependencies (Python3, pip3, venv).
> > 
> > * 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. Personally I really like the template based
> > LineageOS device wiki[4] as it's the same structure for every device but
> > still
> > covers corner cases or important notes. Some time ago I created a proof-of-
> > concept which could be an inspiration for further work[5]. For
> > prioritization a
> > a ranking of popular wiki pages could be used, which devices are most
> > commonly
> > searched?
> > 
> > * The wiki offers guides on how to use the LuCI for common use cases, which
> > is
> > great because it's the most likely way for basic users to interact with
> > OpenWrt.
> > However this could get some extra love: Partly pictures are missing[6],
> > pictures
> > are outdated[7] and/or missing from the web interface overview[8]. This
> > could be
> > refreshed and put in nice overview, maybe even even create click-through
> > videos.
> > There must be tools that automatically click things in UIs and make
> > screenshots,
> > this could make the documentation easily future proof and translatable.
> > A prioritization and general collaboration could happen with the
> > participants of
> > the '"simplified" interface for LuCI'[9] thread. 
> > 
> > I'd be happy to either be a mentor or writer. Hopefully some more people are
> > interested in this efforts!
> > 
> > A first step is the application to make OpenWrt a SoD project. If approved I
> > can
> > (try to) handle the paperwork. The deadline is 4th of May, sorry for the
> > short
> > notice.
> 
> Hi Paul,
> 
> I just noticed the deadline is today at 8PM UTC (in about 4 hours)
> 
> This Season of  Docs is a nice project, but I think it is about actually
> writing documentation instead of creating new infrastructure for writing
> documentation. I also think that we need someone actual writing
> documentation more then new infrastructure for it, so this is a good thing.