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 daily work in our work logs (including successes, failures, and premature "just thinking aloud")
- We document checkpoints whenever we overcome a hurdle, or to keep the community up-to-date on our progress
- We document polished 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.
