Documentation Process

kelu124

June 27, 2016

What is this presentation?

I have been working on a open-source hardware project and documentation is key. A question remains.

I'm lazy, how do I make the documentation process efficient, and as system-independant as possible?

Inputs

I'm working only with a couple of Readmes:

  • One per module (one per folder)
  • One worklog.md file

A ReadMe per folder

We have identified a way to build a module documentation, following guidelines:

  • A Readme.me to get all information
  • A viewme.png for a representation of the module
  • A source and a build folder.

ReadMe's structures

  • ## Module: XX
  • ## Name
  • ## Title
  • ## Description
  • ## IOs
  • ## Key Components
  • ## License

Worklog

  • Several raw notes parts, then..
  • Notes
  • Worklog -- Starting April 5th 2016
  • -------
  • ### 2016-04-05 Title1
  • ### 2016-04-06 Title2 ...
  • Mindmapping
  • ConceptZ->ConceptA

Using Worklog

To generate the blog, and to generate a mindmap of concepts.

It also highlights the TODOs

Generating the blog

All dated elements generate individual posts on the corresponding github page, here http://kelu124.github.io/echomods/.

Mindmap

Worklog generates a mindmap of the concepts I have in mind at the moment.

Using the Readme's

  • The Readme's are used to generate the overall graph of links between the modules
  • The Readmes create the table of modules at /Readme.md
  • They also update the table of progress
  • Last but not least, they create the graph representing how the modules work, internally, connecting the interfaces

Table: modules

Table: progress

Block diagram

Tools used

  • Python and bash for the scripts
  • Graphviz to generate graphs
  • Pandoc to convert documentation
  • gh-pages / Jekyll for the site
  • Reveal.js for the presentations

Conclusion

An efficient (err, lazy) way of documenting. Only one place to edit information, will be updated everywhere, even in this presentation!

Pending Work

  • Publishing automatically a presentation of the modules.. will need some inputs from the /include/ folder =)

Q&A

Or ping me @kelu124 / kelu124@gmail.com !