Visit the forum instructions to learn how to post to the forum, enable email notifications, subscribe to a category to receive emails when there are new discussions (like a mailing list), bookmark discussions and to see other tips to get the most out of our forum!
Standardized software for documentation
  • I get that there are headaches and open source choices are limited, but ... I foresee even more headaches if there isn't some organization and determination of basic, common software to use.

    I've gotten the gist that there's no good open source CAD software ... I haven't really dabbled in CAD except for AutoCAD (which is hugely expensive and not practical when there is and will be a growing need for volunteers to contribute on CAD projects from their home computers; AutoCAD, as have been discussed elsewhere, would obviously be too expensive for regular users to use).  Simply googling around, I found an open source CAD software called "BRL-CAD" at http://brlcad.org/ ... is that not adequate to the needs?  Its my understanding the big notion of "open source" isn't that its free to download and use (though that is, obviously, a huge boon to opening up collaboration to anyone, not just those that have money to spare to buy software), but open development, enabling anyone to contribute.  If we simplify the tools by using a standard common set of open source (or at least free) software, it would be easier ... I think we should always presume that there is always room to improve on every aspect of OSE, including the documentation we produce.  Suppose someone spots a little errant detail on a CAD drawing that's been put in a document, they could fix it themselves if they knew what programs we are using, downloaded the source CAD file, made the fix and uploaded it for the community to decide if the fix was worth having; if everyone is instead using their own programs, they would have to find the particular person who made that particular CAD drawing, inform them, and hope they're active and around to fix it.  The option for someone to spot and fix something themselves I think improves the open source model but, I think, needs a documentation manager to decide what programs we should use.

    For word processing, spreadsheets and the like ... OpenOffice or LibreOffice?  Or maybe Google Documents with its inherent Internet capability?  Should documentation be intended for print, in which case exporting/publishing as .PDFs be a goal (in which case page layout and formatting should be attended)?  Or should we publish everything in a wiki format?  I'm guessing we'll probably want a combination of online and printable formats, but I think we should determine what and which formats.

    If we are going to collaborate on documentation, I think this stuff should be worked out so we're all on the same page (pardon the pun) with the tools we should use.  I think it would be much easier to set these standards early on, then waiting until there's a messy hodgepodge of documentation created with different software and realizing we'll need to go back through and rewrite what's already been written so they conform to a common format and could be readily edited for even minor grammar fixes (or CAD drawing glitches) without having to have a dozen different programs.

    Thanks for time and consideration in reading and addressing my concerns here, and I hope they are received in the constructive manner I intended.  If they were already addressed elsewhere, I severely apologize!
     
  • 4 Comments sorted by
  • Vote Up0Vote Down
    mjnmjn
     
    September 2011
    Some effort has been made in recent weeks to standardize the documentation - at least in the wiki for the GVCS-50.  To me, that's more important that picking which file format we should all use.

    - Mark
     
  • I'm guessing there will eventually be two big instruction publication formats:  the wiki articles, and .PDFs.  Wiki being what it is, its more fluid and dynamic which can actually make it a challenge.

    The forums, I think, are the best current option for actual collaboration, posting incomplete working drafts for OSE peer review/critique/commentary/etc. in threads.  I just think it'd be best for even the working versions (like the .ODT I've been trying to do) to have a consistent application chosen.  Yes, Google Documents can read Open Office documents and vice-versa, but I've already encountered annoying conversion bugs (such as ' marks used in spreadsheets to fix the format of cell contents; the ' marks themselves aren't supposed to display in Google Documents nor Open Office, but for some reason when converting from Google Documents to Open Office, the ' marks became visible and I had to fiddle around with each cell to eliminate them and re-format the cells as text).  I can see the value in Google Documents, but I much prefer OpenOffice because its a more full-featured word processor (and spreadsheet), and I use the features and notice their absence when trying to work in Google Documents.
     
  • Vote Up0Vote Down September 2011
    Howard,
    you may want to look at the Category: Software on our wiki.

    As for a standard for technical documents, LaTeX seems to be a good choice.
    (It might be better to embed LaTeX on the wiki pages whenever it's needed, instead of creating the whole document in LaTeX.)

    This document doesn't attempt to teach you LaTeX but it does pick out some issues that arise when people start producing long documents. LaTeX was designed with technical reports very much in mind, so before you consider using any other method, look at the list of LaTeX's strengths first.
     
  • From that LaTeX's strengths list, they also list weaknesses, including this one:

    • LaTeX's not good at flowing text around pictures.

    A basic fact of the documentation we are to produce means we must include diagrams that go with the text.  Awkwardness involving this could be problematic, trading one problem (OpenOffice's ugly fractions) for another (LaTeX awkwardness of flowing text around graphics).  I have never used LaTeX before, and don't know if the others on the Documentation have, either.  I'm pretty sure all have used OpenOffice, so LaTeX comes with a learning curve disadvantage.  I'm confident I could learn it, but it would take time, and it appears it is going to take a lot of time, as it is, to complete the document I am working on as it is (its taken several days to get the information I need to complete the first actual instruction page for how to build a part of the CEB Press; multiply a few days by 20 or so parts and that's how many days it will take to complete).

    I thank you for the suggestion, and will try to learn LaTeX while waiting for confirmation on CEB Press part dimensions, but after reading its advantages/disadvantages, I am inclined to continue to believe a plugin extension for OpenOffice would still be a preferred option at this point.
     

Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Login with Facebook Sign In with Google Sign In with OpenID Sign In with Twitter

In this Discussion

Tagged

Loading