Technical Report system? | General | Forum

Post edited 2:20 am – March 30, 2010 by Luke Maurits

This is something I have been thinking about for a while, but never bought up on the forums:

I think it would make a lot of sense for us to having some sort of Technical Report system: a system for naming, storing and categorising reports written by our community on technical matters. These would have reference numbers like CTR-001 or something (CTR = CSTART Technical Report). These could be used to contain things like, e.g. the orbit simulations I did a long, long time ago, which are too complicated to really put in a Wiki page. Pages in the Wiki, especially those associated with the Engineering Process, could make reference to these. E.g. when describing the various options available for solving a particular Design Task, it would be great to be able to say "If we take this approach, then the maximum acceleration experienced during reentry will be 4.8 gs – see CTR-042 for details", where CTR-042 would contain all the details of and output from a computer simulation or the like.

I think a system like this will be pretty much necessary for the Engineering Process as currently envisaged to work. Not only that, but writing these documents would be something we could start on now which (i) can be quite useful – if CSTART achieves nothing else in its life but generating a large database of good quality, CC licensed reports on aspects of spaceflight, that would still be a pretty awesome achievement; (ii) can be made ITAR free. If when we write these reports we only make reference to publications which are general knowledge or are in the public domain (as defined by ITAR), and do not expand upon this knowledge, then the reports should be ITAR free as well; (iii) gives us something to do newcomers: everytime someone with an engineering degree or the like comes along, we can point them to the archive of Technical Reports and say "Write some more of these, and/or expand and correct the existing ones!", and this is a substantial, well-defined task they can get to work on if they are interested.

This would also help a lot with copyright issues. Recall that I recently found some very awesome articles on using ballutes for reentry on lunar return trajectories, and posted them to the forums, but people couldn't see them because they were behind a copyright barrier that you could only pass by using a computer at a subscribed university. For CSTART to redistribute those files would constitute copyright violation, but for one of us to write a report summarising the details of those papers, with references, and publish that report under a CC licsense would be entirely Kosher.

I would be happy to start a bunch of these reports in the nearish future. I just borrowed some very handy books from my university library ("Space Vehicle Design" by Michael Griffin and James French and "Spacecraft Navitation and Guidance" by Maxwell Norton. Condensing relevant parts of these books into technical reports is a good way to legally share the knowledge around.

Do people think this is a good idea? If so I guess we should figure out some basic guidelines for this. Storing the reports in the Mercurial repository seems like a no-brainer. Once we have decided on things like a numbering scheme, etc., we could make a nice LaTeX template for reports, like the one Denis made for the OHKLA Overview Document.

EDIT: If we do follow this path, it would be a great idea to find or write some software to let us manage the documents very nicely, e.g. categorisation, tagging, full-text search, etc, etc.

I agree that the LaTeX barrier to entry is probably a problem.  It's a shame there's just no other way to get documents looking quite so nice (also, the excellent maths support will be pretty much essential).  I've never actually used Lyx, I've always assumed it wouldn't quite work right (the same way that WYSIWYG website creators always produce horrendous HTML code), but I guess I should look into it.  Maybe we could adopt a policy where technical reports are started as Wiki pages (which is about as accessible as possible) and then get translated into LaTeX by someone with the skills once the report is finished?  This would also allow people to work on reports incrementally without having to master Mercurial first.

With regards to the numbering schemes, I agree that we don't want anything confusing, but I feel like we need something to make it easy to reference them.  Surely CTR-x, where x is simply a zero-padded number which is incremented for each report is acceptable?  This is basically the same system used for internet RFCs, as far as I know.

I agree on the minimal requirements.  Writing one of these should be inviting, not formidable.

brmj said:

I think you misjudged my intent. CTR-x style numbering would be great. I was more stating my objection to more complex systems that might try to designate topic, workgroup, aplicable project(s), or anything of that nature. Maybe this was obvious enough that I shouldn't have mentioned it in the first place.

Aah, gotcha.  I agree that we should avoid anything really complicated like that.  If a technical report is applicable only to a particular project, then that can be made adequately clear in the title and/or abstract.  I think a lot of the early reports could/should be quite general purpose, anyway.

Personally, I am not super keen on a hierarchical numbering system, mostly because it feels like the complexity:benefit ratio is too high.  It introduces the need to look up what the first part of a new report's number should be in some big table, the need for someone to maintain that table (how do we decide when to create a new topic?), etc.  All of this would be okay if it solved some massive problem, but I don't see that it buys us anything we couldn't already get out of a simple tagging system.

Also, I feel like we should try not to let the technical report system get too heavily tied to particular projects.  I think it would be useful to have quite general documents (like "An Overview of Atmospheric Reentry", say, something I would like to write soon), and for people to be able to use technical reports as part of project proposals (like "A Basic Feasability Analysis of Using Rockoons for Orbital Insertion").  This kind of open-endedness is probably incompatible with any numbering scheme, or at least any numbering scheme of practical value.

Also to make it more accessible to users can we do the same thing on the forum itself? We have a good tagging system in the forum software and also a good search feature. This could be good for generic topics, not sure about complex technical reports which require mathematical expressions.

Merits

- Easily accessible, any can create/comment/edit the topics

- Already a system in place. We can get this up and running in less than 10 minutes.

- Tagging system and search features to help find stuff.

Demerits

- Can't be used for technical reports.

Okay, after this exchange I am now pretty strongly in favour of using the wiki to implement the Tech Report system.  Conversion to LaTeX and pdf can be handled by scripts as we deem necessary.

brmj, what did you have in mind with regards to a template?  Beyond absolute basics, like Title, Author and Abstract, do we want to enforce any other structure?  Thinking about it, maybe we should leave Author out, since it's a wiki and is likely to be edited by a host of people.

I am quite keen to start on a few of these soon, so would be happy to see the templating issue sorted out ASAP.  Or should I just go ahead with the first report and we can beat it into template form as we go?