Documentation - Revision history

Maltfield: /* Sphinx */ added praxis to sphinx sections

2026-04-21T22:10:02Z

Sphinx: added praxis to sphinx sections

← Older revision		Revision as of 22:10, 21 April 2026
Line 46:		Line 46:

	# Theory (Design rationale)		# Theory (Design rationale)
			# Praxis (Examples of actual builds, with photos, location and contact info)
	# Building Instructions (How to make the tech)		# Building Instructions (How to make the tech)
	# Usage Instructions (How to use the tech)		# Usage Instructions (How to use the tech)

Maltfield: /* Sphinx */ added min sections for hardware docs on sphinx

2026-04-21T22:08:57Z

Sphinx: added min sections for hardware docs on sphinx

← Older revision		Revision as of 22:08, 21 April 2026
Line 43:		Line 43:
	Sphinx holds Eco-Libre's final & polished documentation.		Sphinx holds Eco-Libre's final & polished documentation.

	The purpose of the documentation on Sphinx is to clearly show "how to build" our projects.		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)
			# 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.		The target audience for our Sphinx documentation is community builders, collaborators, and volunteers.

Maltfield: added link to OSHWA guide

2026-04-21T22:06:05Z

added link to OSHWA guide

← Older revision		Revision as of 22:06, 21 April 2026
Line 78:		Line 78:

	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.		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.

			== Further Reading ==

			* [https://oshwa.org/resources/sharing-best-practices/ Best Practices for Open Source Hardware by OSHWA]

Maltfield: /* Why? */

2026-04-01T18:16:54Z

Why?

← Older revision		Revision as of 18:16, 1 April 2026
Line 8:		Line 8:
	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.''		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 our unrefined & unpolished ''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 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		# We document polished & refined releases, clearly describing how to build our tech

	== Who? ==		== Who? ==

Maltfield: /* Wiki */

2026-04-01T17:01:51Z

Wiki

← Older revision		Revision as of 17:01, 1 April 2026
Line 75:		Line 75:
	The target audience for our Wiki documentation is other Eco-Libre volunteers.		The target audience for our Wiki documentation is other Eco-Libre volunteers.

	Do ''not'' use the wiki as a place to write how-to guides (wordpress) or formal build documentation (sphinx). Just use it as a dumping ground as you iterate.		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.		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.

Maltfield: /* Wordpress */ fix broken external linik

2026-04-01T17:00:19Z

Wordpress: fix broken external linik

← Older revision		Revision as of 17:00, 1 April 2026
Line 56:		Line 56:

	=== Wordpress ===		=== Wordpress ===
	Wordpress holds Eco-Libre's website [[www.eco-libre.org]]		Wordpress holds Eco-Libre's website [https://ww.eco-libre.org 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 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).

Maltfield: /* Where? */

2026-04-01T16:58:55Z

Where?

← Older revision		Revision as of 16:58, 1 April 2026
Line 38:		Line 38:
	Eco-Libre publishes different documentation on different platforms.		Eco-Libre publishes different documentation on different platforms.

	This is not redundant, it's a ''process'' of refinement ~~and different~~ platforms are leveraged for their strengths and tailored to different audiences.		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 ===

Maltfield: /* Wiki */

2026-04-01T00:37:22Z

Wiki

← Older revision		Revision as of 00:37, 1 April 2026
Line 77:		Line 77:
	Do ''not'' use the wiki as a place to write how-to guides (wordpress) or formal build documentation (sphinx). Just use it as a dumping ground as you iterate.		Do ''not'' use the wiki as a place to write 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.		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.

Maltfield: /* Wiki */

2026-04-01T00:36:22Z

Wiki

← Older revision		Revision as of 00:36, 1 April 2026
Line 69:		Line 69:

	=== Wiki ===		=== Wiki ===
	Mediawiki holds our ~~developer~~'s work logs and any other documentation that does not fit into Sphinx or Wordpress.		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 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.

Maltfield: added wiki

2026-04-01T00:33:58Z

added wiki

← Older revision		Revision as of 00:33, 1 April 2026
Line 67:		Line 67:
	# Join us (linking them to the volunteer application page)		# Join us (linking them to the volunteer application page)
	# Donate (linking them to the donate page)		# Donate (linking them to the donate page)

			=== Wiki ===
			Mediawiki holds our developer'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 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.