Documentation site structure - thoughts?

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 site structure - thoughts?

Post by Fred »

http://docs.freeems.org/

First of all, I plan on having a manual.freeems.org site too for user instructions, setup for hardware, etc etc. This will exist for other types of firm docs such as the doxygen stuff and other standalone items such as currently found in the docs directory of the source tree.

I guess what I want to hear are ideas about what we might need. I don't want to make the tree of URLs too shallow as that would be limiting later on.

I foresee :

A top level page with links to other forms of docs like the manual, forum, wiki etc and links to the available content further down the tree on this domain :
  • General docs?
  • Software docs
  • Hardware docs
For software I expect :
  • Tuning - on a pc or cell phone or psp or whatever
  • Firmware - on an xdp512 based device running an engine or other function on the car
Below tuning, each tuning apps name and below firmware, each firmware branches name. Below each branch/app an index and then access to older stuff via version number or date

For hardware it will likely end up divided like so :
  • Free - Designs available under suitable license - DIY and/or commercial built.
  • Commercial DIY Built (boards ah la MS)
  • Commercial Assembled (devices ah la Motec, MS-PNP, etc (still must use FreeEMS firmware))
Below each category will be named setups and below each of those versions if applicable. Where something fits two categories it's docs will be in one place with a mention and link from the other.

So, the first task is where to keep the doxygen stuff and the existing firmware docs.

Code: Select all

http://docs.freeems.org/soft/firm/vanilla/doxy/<version>/index.htm etc
Or maybe long versions :

Code: Select all

http://docs.freeems.org/software/firmware/vanilla/doxygen/<version>/index.htm etc
Or maybe it is silly to have software/firmware and software/tuning

Perhaps top level of :
  • General docs?
  • Firmware docs
  • Software docs
  • Hardware docs
would be better?

You may be thinking "shed colour" but getting it wrong up front means redirects and 404s later, so it should have some thought put into it now IMO.

What have I done wrong, what is missing, positive reinforcement etc please.

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!
User avatar
longracing
LQFP112 - Up with the play
Posts: 140
Joined: Wed Jul 16, 2008 9:21 am
Location: NSW, Australia

Re: Documentation site structure - thoughts?

Post by longracing »

I think having Software seperated into Firmware, tuning could be useful for those who just want to inject their car without delving too deep into the firmware/code side of things.
Then again maybe everyone interested in this project is the type that is interested in every aspect of what goes on in their vehicle (tinkerer's like me :mrgreen: ).
User avatar
Fred
Moderator
Posts: 15431
Joined: Tue Jan 15, 2008 2:31 pm
Location: Home sweet home!
Contact:

Re: Documentation site structure - thoughts?

Post by Fred »

Yeah, I agree, good call :-)

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