Battlemesh test docs

29th July 2015 in Thoughts Tags: battlemesh, event, wireless-community

This is going to be my fourth battlemesh!

I was not satisfied with how the test results were published so I volunteered on this task to help out.

I just finished the first version of the Battlemesh Test Docs.

I hope we'll use it as a baseline for ongoing improvement and start to publish human readable documentation and results at the end of each year edition.

The documentation source format is reStructuredText and it's hosted on Github while the browsable website is hosted on readthedocs.org.

The repo structure is prepared to host the documentation and the results of multiple battlemesh editions, starting from the v8 edition, although past editions can be added if anyone will volunteer to do that.

I find this kind of solution much better than wikis because of the several advantages it gives:

  • the documentation can be built easily in different formats: HTML, PDF; EPUB
  • the documentation can be built offline
  • it's possible to work on it offline
  • it's possible to work on it with your favourite text editor instead of a web interface, which is likely to result in increased productivity and less time wasted fighting with wikis
  • reStructuredText can be easily converted in other formats (eg: markdown)
  • it's very easy to publish it on the amazing readthedocs.org
  • managing and browsing translations is straightforward
  • managing and browsing different versions is straightforward - even though it doesn't apply in this case (we'll likely have 1 version only which is updated over time)
"Wikis are where documentation goes to die."
Jacob Kaplan-Moss

See you in Slovenia!

Retweet

Comments

Leave your comment

Categories

Let's be social

Popular posts

Latest Comments

  1. Hi Julio! I missed your comment a few years ago but I'm glad you are working with OpenWISP, I'll try to reach you in private :-)

    By Federico Capoano in A Turning Point in my Life, Community Networks and OpenWISP

  2. Great news Aymará! Very happy to know this post has inspired you to experiment :-)

    By Federico Capoano in First DjangoGirls Rome wrap-up & afterthoughts

  3. Hi!! I'm a Django Girls coach too. Here, in Argentina, made just what you suggested, splited the workshop in two days. The experiment went just great! Most of the girls achieved to publish the blog from ground 0. It feels great to be helpfull ...

    By Aymará in First DjangoGirls Rome wrap-up & afterthoughts

  4. Send any question to the interop-dev mailing list or open an issue on github.

    By Federico in Network Topology Visualizer: django-netjsongraph

  5. I have a question about Network Topology Collector, can you brief me pls?

    By Nasrin Akter in Network Topology Visualizer: django-netjsongraph

Popular Tags

battlemesh censorship creativity criptography django event fosdem google-summer-of-code ibiza inspiration javascript jquery linux nemesisdesign netjson ninux nodeshot open-source openwisp openwrt performance photo programming python security staticgenerator talk upload wifi wireless-community