Documentation
This page will describe Eco-Libre's approach to documentation, which platforms we use for what, and why.
Why?
Documentation is critical. It's a core component of Eco-Libre's mission statement.
We don't approach documentation as an afterthought. As an Eco-Libre volunteer, you should expect to spend ~50% of your time writing documentation describing your work.
Another common mistake is to hold-off on documentation indefinitely "because it's not ready" -- that's not what we do at Eco-Libre. We document everything.
- We document our unrefined & unpolished daily work in our work logs (including successes, failures, and premature "just thinking aloud")
- We document polished checkpoints whenever we overcome a hurdle, or to keep the community up-to-date on our progress
- We document polished & refined releases, clearly describing how to build our tech
Who?
Eco-Libre volunteers should always consider their audience when writing documentation. Different groups of people will have different levels of knowledge & engagement with our work:
Casual Internet User
The "Casual Internet User" has probably never heard of Eco-Libre before. They may not be familiar with concepts like Libre Licensing. They may have just stumbled on our website from social media. And, when we write articles targeting this audience, it's important that we write superficially -- showing concrete results (eg a video of a machine actually doing work) while also explaining Eco-Libre's mission, and why it matters.
The "Casual Internet User" needs to read WHAT our project does and WHY it may be helpful for WHO. They are less interested in HOW. Instead of writing HOW, make the CTA a link to the actual (sphinx) documentation.
Community Builders
The "Community Builders" are people actually building our tech for their communities.
The "Community Builders" may never open FreeCAD, but they will read our sphinx documentation.
Community Collaborators
The "Community Collaborators" are people who will modify our work and, hopefully, they'll do minor collaborations that improve our designs.
Eco-Libre Volunteers
Eco-Libre Volunteers are the backbone of Eco-Libre.
You will likely pickup a project from a former Eco-Libre Volunteer. And you will likely pass-on your project to a future Eco-Libre volunteer.
Eco-Libre Volunteers are going to benefit by your most-verbose-possible documentation. They want to know your successes. They want to know your failures. Documenting this (in your work logs, in excruciating detail) is key to prevent Eco-Libre Volunteers from making the same mistakes year-after-year.
Where?
Eco-Libre publishes different documentation on different platforms.
This is not redundant, it's a process of refinement (wiki -> wordpress -> sphinx). Different platforms are leveraged for their strengths and tailored to different audiences.
Sphinx
Sphinx holds Eco-Libre's final & polished documentation.
The main purpose of the documentation on Sphinx is to clearly show "how to build" our projects. It should include sections on:
- Theory (Design rationale)
- Praxis (Examples of actual builds, with photos, location and contact info)
- Building Instructions (How to make the tech)
- Usage Instructions (How to use the tech)
- Maintenance Instructions (How to maintain the tech over months, years, and decades)
The target audience for our Sphinx documentation is community builders, collaborators, and volunteers.
Sphinx is an ideal final documentation platform, because:
- It's versioned (different historical versions matching previous releases)
- It can be viewed in html (desktop or mobile) or downloaded (epub or pdf for a physical paper book)
- It's powerfully extendable with custom directives, so we can do things like stitch BOM spreadsheets into the docs, or make video embeds fall-back to QR codes, if rendered to paper
Our Sphinx documentation should be polished, clean, straight-forward, and a relatively fast read (no paragraphs-long tangents on design decisions or historical context info). You an provide short tips on "what not to do", but don't spend paragraphs. Instead, just a couple sentences and link back to wiki logs or wordpress articles that describe historical mistakes for additional information to the reader.
Wordpress
Wordpress holds Eco-Libre's website www.eco-libre.org
The purpose of the documentation on Wordpress is marketing. We use it to write articles describing releases and major milestones (or major failures). Every article is promoted on social media, with a link back to the article (the purpose of social media is to drive traffic back to our wordpress site).
The target audience for our Wordpress documentation is Casual Internet Users.
At the bottom of every Wordpress article, there should be 1 main CTA. The purpose of these articles should be to push new viewers to either:
- Build our tech (linking them to the Sphinx documenation)
- Join us (linking them to the volunteer application page)
- Donate (linking them to the donate page)
Wiki
Mediawiki holds our volunteers's work logs and any other documentation that does not fit into Sphinx or Wordpress.
The purpose of the documentation on the Wiki is to provide a chaotic space for you to write anything and everything describing your work at Eco-Libre. Be verbose. Don't try to make it clean or polished. Use this space to write your thoughts, ideas, mistakes, and journey. Eventually, once you reach a major milestone (or catastrophic failure and need to change course), you can collect your thoughts from the wiki and write an article for the wordpress site.
The target audience for our Wiki documentation is other Eco-Libre volunteers.
Do not use the wiki as a place to write polished how-to guides (wordpress) or formal build documentation (sphinx). Just use it as a dumping ground as you iterate.
There is no such thing as publishing your findings too early on the wiki. Just puke unrefined information onto it as you make progress. The more verbose you are (in both your successes and your failures), the more you're likely to help someone who comes after you.
