Documentation Source Separation

FreeEMS topics that aren't specific to hardware development or firmware development.
Post Reply
User avatar
Fred
Moderator
Posts: 15431
Joined: Tue Jan 15, 2008 2:31 pm
Location: Home sweet home!
Contact:

Documentation Source Separation

Post by Fred »

Currently there are a lot of docs in the firmware. Many of them are binary files and I don't like committing against them in the firmware repo. Additionally, I don't like having to merge people's work into the firmware when it isn't really firmware related. We need to make some changes:
  • Some of the docs should stay in the firmware docs dir, but others should come out.
  • Some should stay on OD formats
  • Some should be changed to markdown
  • Some should be in LaTex
And maybe other changes?

This seems like a good time to split out some of the documents to different places and figure out which formats each should be available in and add licensing to them. Currently none have licensing and I would very much like at least some of the FreeEMS docs to be non-free. The reason for that is to maintain a single golden source of them, right here. Having 50 copies, 49 of which are out of date is not helpful. Backups will be taken and a mechanism for mirroring provided, but the source must be here, and it must be singular. I guess it might be a good idea to header the docs with "If you're not viewing on FreeEMS.org, the original version of this document can be found here!" statement as seen on many sites that get plain copied.

The trouble is, I have no knowledge of closed source licenses suitable for interface documentation such as the comms core spec. Some docs, such as that one, should not even be modified by others, however distribution in some ways should be permitted regardless of that. This needs to be executed very carefully to ensure it works as intended and doesn't backfire as ms2e 3.2's license change just did :-/

This has been on my mind for a long time, I've just not found time to sort it out until now.

Now, which files are there? Let's take a look and present a full listing here and a comment on each deciding what happens to it. This section is fully up for discussion, please comment. I've created an issue here to track progress on it: http://issues.freeems.org/view.php?id=397

Belongs in firmware as is:

Code: Select all

./calculators/dwellTime.ods
./calculators/injectorDeadTime.ods
./calculators/warmUpCurve.ods
./MissingTeethValidCombos.ods
./MainTableValidSizes.ods
./Doxyfile
./git/config
./licenses/gpl.template.bash
./licenses/gpl.template.c
./licenses/gpl.template.h
./licenses/gpl.v3.full.txt
Belongs in firmware or deleted, but maybe with format change. Needs to be cleaned up and cleared out or put into production:

Code: Select all

./dev/release.pre.tests.txt - needs to move into a formal release procedure document, probably in markdown
./dev/release.procedure.txt - updated, needs to be formalised.
./dev/serial.imp.issues.txt - updated, but needs to be transferred to the issue tracker
./dev/tasks.txt - updated, but needs to be transferred to the issue tracker
./interface/FreeEMS-DDL.mm
./interface/FreeEMS-DDL.xsd
./interface/FreeEMS-XML2C.xsl
./interface/IFreeEMS-Vanilla-DDD.xml
./interface/IFreeEMS-Vanilla-Specific-Serial-Protocol.odt
./interface/DataMapStructure.odg - what is this?
./interface/draftsAndIdeas/basicDatalog.txt
./interface/draftsAndIdeas/DatalogExample.js
./interface/draftsAndIdeas/IFreeEMS-Vanilla-Interface-Data-Map.js
./interface/draftsAndIdeas/IFreeEMS-Vanilla-Interface-Packet-Descriptions.js
./interface/draftsAndIdeas/IFreeEMS-Vanilla-Interface-Structure-Descriptions.js
./interface/draftsAndIdeas/SettingsExample.js
./interface/draftsAndIdeas/some.good.default.data.and.curves.xml
./interface/draftsAndIdeas/structure.relationships.description.txt
Needs to move to a different repository. Some should become latex and have an HTML version be linked from the firmware and itself link to the latex source:

Code: Select all

./FreeEMS-PinAssignment-XDP512.ods - hardware guide, nothing to do with firmware, except that firmware defines how it should look, migrate to another format or keep it and change format somewhat inside?
./FreeEMS-HardwareStandards.odt - formal spec, belongs in latex for both html and pdf
./FreeEMS-FirmwareSerialImplementation.odt - white paper style, belongs in latex for both html and pdf
./FreeEMS-MemoryManagement.odt - exists in latex, remove?
./FreeEMS-SerialProtocolCoreSpecification.odt - exists in latex, remove?
./latex/FreeEMS-MemoryManagementScheme.tex
./latex/FreeEMS-SerialProtocolCoreSpecification.tex
./latex/FreeEMS-template.tex - keep this in the docs repo only
./FreeEMS.mm - maybe not latex for this one, perhaps something else like PlantUML
./FreeEMS-MinToMaxBasicConfigurations.txt - hardware design guidelines to be moved into latex
./latex/logos/diyefi.eps
./latex/logos/diyefi1.png
./latex/logos/diyefi2.png
./latex/logos/freeems.eps
./latex/logos/freeems.png
./latex/README
I'm hoping that we can link to web images for builds as well as local ones? or even web include images in pdfs?

Migrated all of this to a migrate directory ready for the move. More work to be done.

Fred.
DIYEFI.org - where Open Source means Open Source, and Free means Freedom
FreeEMS.org - the open source engine management system
FreeEMS dev diary and its comments thread and my turbo truck!
n00bs, do NOT PM or email tech questions! Use the forum!
The ever growing list of FreeEMS success stories!
johntramp
LQFP112 - Up with the play
Posts: 119
Joined: Sat Apr 24, 2010 1:42 am
Location: New Zealand

Re: Documentation Source Separation

Post by johntramp »

How do we know which format (Latex/OD/Markdown) should be used for different types of documents?
User avatar
Fred
Moderator
Posts: 15431
Joined: Tue Jan 15, 2008 2:31 pm
Location: Home sweet home!
Contact:

Re: Documentation Source Separation

Post by Fred »

So far, spreadsheets stay in open office format, and all the formal specification documents which are formal in style belong in latex. markdown is suitable for more casual docs, or so it seems. I think .txt files have a limited future in that repo.

I see the following being used in future: .md .ods .plantuml .tex

I guess the rules would be something like:

Spreadsheet = ODS
Needs to be read in a text editor and optionally displayed as HTML = MD
Needs to be published formally as a document and displayed as HTML = TEX
Diagrams should be written in some sort of textual source format such as plantuml

Fred.
DIYEFI.org - where Open Source means Open Source, and Free means Freedom
FreeEMS.org - the open source engine management system
FreeEMS dev diary and its comments thread and my turbo truck!
n00bs, do NOT PM or email tech questions! Use the forum!
The ever growing list of FreeEMS success stories!
Post Reply