Serving the Quantitative Finance Community

 
User avatar
rmax
Topic Author
Posts: 374
Joined: December 8th, 2005, 9:31 am

Documentation

October 28th, 2011, 9:12 am

Another stub post. Fully expect this thread to be about as popular as Christmas time with Turkeys.Joking aside, this is important and anything released must have good clean documentation associated with it.In essence I think there are four layers of documentation:1. High-level: User manual / Project Process / Requirements etc2. Design - how the interface operate. Object relations etc (probably use UML for the diagram as for most people that would make sense) - should include a coding standard here as well for each language implemented3. Implementation - detailed descripitions of how elements and libraries work4. Comments in code. Might need to publish some tips/standards on this as well to ensure there is a degree of commonalityWill try and being to write the Project Process stuff once I get a chance...
 
User avatar
Cuchulainn
Posts: 20250
Joined: July 16th, 2004, 7:38 am
Location: 20, 000

Documentation

October 28th, 2011, 9:39 am

I can do it for those who don't have the time to do it (euphemism ). "Good Heavens! For more than forty years I have been speaking prose without knowing it". Seriously, expert knowledge is implicit and developers have diffculty and/or no interest in documenting. Read my lips; no doc <==> no user base. Have people here read "Mythical Man-Month" by Fred Brooks? He knows the answer. "The Bible of Software Engineering", because "everybody quotes it, some people read it, and a few people go by it." Don't fall into this trap.
Last edited by Cuchulainn on October 27th, 2011, 10:00 pm, edited 1 time in total.
 
User avatar
rmax
Topic Author
Posts: 374
Joined: December 8th, 2005, 9:31 am

Documentation

October 28th, 2011, 10:41 am

I think we end-up with a release principle which is if the functionality/capability is not documented then it does not get released. This should ensure that everything in the trunk has good solid documentation.
 
User avatar
rmax
Topic Author
Posts: 374
Joined: December 8th, 2005, 9:31 am

Documentation

October 28th, 2011, 12:37 pm

Agreed - will set-up a new thread for tests!
 
User avatar
rmax
Topic Author
Posts: 374
Joined: December 8th, 2005, 9:31 am

Documentation

October 28th, 2011, 1:44 pm

QuoteOriginally posted by: outrunI think a practical way forward would be to start on two component1) Cuch's FDM GOF2) A minimalist function lib with some math and exotic pricing routines..and use those as a future blueprints: It would allow us to go from conceptual sketch talk to a more concrete example with much more detail on these subjects.Maybe we should even focus on getting a super simple Black & Scholes model released. It will not cover all aspect yet we will run into, but it would allow us to make notes wile doing it, fill in information gaps, and build that blueprint.Agreed.If we got the design on that sorted, then we can move on and factor in the more exotic/estoric stuff. I wrote something about this on one of the threads. I think a prototype would be a really good idea. Something like a BS model initially and then something like a Swap (purely because of the more complex inputs into terms of yield curves, cashflows etc). A simple 0.1 release kind of thing.
 
User avatar
Polter
Posts: 1
Joined: April 29th, 2008, 4:55 pm

Documentation

November 3rd, 2011, 9:42 pm

Hey, outrun, have you seen this thread -- http://article.gmane.org/gmane.comp.lib ... ation/4660 -- ?DocBook to LaTeX Publishing was mentioned, looks interesting:http://dblatex.sourceforge.net/http://d ... 03s06.html
 
User avatar
rmax
Topic Author
Posts: 374
Joined: December 8th, 2005, 9:31 am

Documentation

November 4th, 2011, 10:22 am

Nice document outrun! I think the items you mention above come down to the branding. Looking at other open source projects they are just not inviting to read and look at.
 
User avatar
rmax
Topic Author
Posts: 374
Joined: December 8th, 2005, 9:31 am

Documentation

November 4th, 2011, 10:29 am

Would also be good to have a higher level doc which shows the plan of various elements... a kind of summary of the architecture as not sure how these elements interact as yet (and even in the ISS they knew what they were trying to build and what the standard interfaces were).