Git and Extreme Enterprise
Should we use Git or tools for mere commoners as we pursue Extreme Enterprise?
Maltfield Log Sez]]
Hey Marcin,
I just finished documenting the alpha release of the BusKill app. I'm using Sphinx and Read the Docs, which is the gold-standard of documentation (a *lot* of open source projects host their docs on Read the Docs):
* https://docs.buskill.in/
I'm not sure if you saw my write-ups on Continuous Documentation, but I recently published a two-part series about hosting this solution for free on GitHub Pages:
* https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/
There's a number of advantages of Sphinx/Read the Docs: Sphinx has built-in support for multiple output formats. I write it for html (docs.buskill.in), but it automatically builds PDFs and EPUB files for offline use. It also looks great on both small-screen mobile devices and big-screen desktops.
The sources of the documentation are written in reST markup, which makes them easy for folks to view & edit in GitHub
reST allows users to write custom directives in python, making it very powerful for custom/advanced needs (such as transforming a BOM spreadsheet into a table when the docs are built)
Because it's integrated with Git, it has the best version control that "just works" -- readers can immediately switch between different git-tracked versions using the lower-left "Alternate Versions" menu. This would be great for quickly going back-in-time to view previous releases of our machines.
Users can also switch between different language translations using the lower-left menu. I understand you've been in communication with Melanie. Knowing she's an expert in technical documentation, I first reached out to her in June when researching this documentation solution.
I've been thinking a lot about how this could benefit OSE, namely the Civilization Starter Kit. I think it's important to have the CSK in PDF format, but right now there's no easy way to update it. This Sphinx/Read the Docs solution would finally make the CSK sources accessible to editors and allow us to setup GitHub Actions to automatically build & deploy a new PDF whenever a change is made, once a quarter, or whenever we want. Let me know if you're familiar with Sphinx or Read the Docs and if you have any thoughts on using this tech for the CSK.
Cheers, Michael Altfield https://www.michaelaltfield.net
MJ Sez
The solutions you point to are useful for power users. If we have sufficient power users, then we can include more advanced documentation formats and this should indeed be done, such as you or G Log are doing already. The priority is wider involvement of people who may not be as technical, so the use of simple tools like wiki and docs (with their inherent issue of being proprietary - but right now the lowest entry level to updateable docs that can be exported to PDF or other formats is live editable google docs). At this point, the critical part is documentation existing, and being organized. That is the case with Template:Dev+ and Template:Enterprise, which we have already moved into native wiki as opposed to Google Docs. That is the case on the wiki, even though it's not well communicated. So we can implement what you are saying. I think that the biggest test of completion is viable business models(CSK v1 sucks at this), which once developed, are the instantiation that can be documented. Given limited resources, the overall focus from my point of view should be moving forward as opposed to documenting. We are still solving for people showing up, as the Extreme Enterprise in development now aims to address.
As we gain more traction, we can spend more effort on more advanced documentation routes. But please note the inherent conflict between such power user-level documentation and our Extreme Events - such as Extreme Enterprise being planned for 2000 participants over one weekend. It is not possible nor desirable to have 2000 git-savvy users participate in the Extreme Enterprise event - we need a broad range of skill sets while allowing for onboarding in a matter of 2-3 hours of training for the Extreme Enterprise event. 2-3 hours is a realistic expectation for the absolute minimum time spent learning the basic OSE Collaboration Protocol stripped down to essentials that allows 2000 people to work effectively together over a weekend. We teach them the collaboration skill before the event. I think getting traction a la viable enterprise is the first goal now. Does this make sense?
MJ
