1. 9

My employer is still using Microsoft Word and Excel to document requirements, specifications, use-cases, test procedures, etc.

I’ve been taking a look at some alternatives to suggest to my colleagues. I’m especially interested in tools that could either be easily integrated with a revision control system like git (i.e. be human-readable in plain text), or provides its own system for branching, merging, and version control.

  1. 2

    We used a template that we’d shove into Huboard–which would then open issues in Github.

    So, Github was always the backing store for our stuff, which made migrations/viewing in other places easier.

    We wrote a bot to crawl the “Requirements” section of the template and then scrape @signoff directives in the issue comments to assemble reports for coverage and whatnot–this gave us handy lists of what had and had not been covered by testing, by whom, and on what dates.

    The “use-cases” and other business goop ended up on a wiki, along with the technical and prototyping information. We kept those two spaces separate because the last thing you want is MBAs cluttering up your technical discussion (or your bikeshedding distracting them from their client use-case work).

    The biggest thing though was making sure that, for devs, this was basically painless and part of the normal process; otherwise, people balk at the paperwork and the system withers and dies (but not before consuming outsized reources!).

    1. 2

      We use Atlassian for everything, except discovery (for that we use Jama and sync to Jira). It’s the only set of tools that works well enough cohesively. It’s really easy to link things together across the systems of Jira/Confluence/Bamboo/BitBucket

      1. 1

        At my company, we use RallyDev, JIRA, and GitHub because different teams are used to different products. Last summer we were also using Code Collaborator for code reviews, but I managed to, as an intern, convince my team to completely eliminate Code Collaborator by switching to GitHub pull requests for code reviews. We still use RallyDev to manage the iterations, JIRA to receive bug reports (because anyone can access JIRA from within the company), and GitHub for code reviews. When management receives a bug report from JIRA, they just paste the link to JIRA in the subject of the RallyDev user story or defect.

        If anyone has recommendations on how to make this really easy, I’d love to hear it.

      2. 1

        Yes, org-mode comes with any Emacs install. Since it’s plain-text, it can be versioned with Git (or any other version control system). Org documents can be exported to a variety of other different formats including Word (via org->odt->doc/docx) and PDF (via org->tex->pdf).

        Orgmode features code-blocks (the equivalent of reStructuredText’s code directives ). These are extremely useful since they can be run inside the document, and their result can be included in the document, either in the form of syntax highlighted source code or the results of that source code (data, images, or anything else that the code block generates) or both. For the code blocks, a wide variety of languages are supported (some of those languages are DSLs for drawing diagrams, sketches, for example you can design simple UI mockups via plantuml code blocks).

        So you can include diagrams about systems, UML use-cases, it also has tables (fully equipped with excel-like formulas), you may also use state-diagrams to describe the test procedures you mentioned.

        If you have larger documents to write, you may also benefit from #+INCLUDE directives that org-mode provides you with. This helps separate your document into sections/chapters.

        Other use-cases include:

        Having said this, Word and Excel remain the #1 word processor and spreadsheet programs out there. Orgmode, as complete as it may be, is tailored for technical people who can take advantage of its features.

        1. 1

          I put as much as makes sense into Org-Mode. For test procedures I put them in shell scripts as much as possible, those should be completely automated.

          1. 2

            I put as much as makes sense into Org-Mode.

            Second that, for everything I don’t need to share authorship with others at least! Saying that, Org mode is pretty decent at sharing, actually, since Github has pretty decent supports for .org documents, both as files in a repo and as gists. Using gist/yagist for creating/updating Gists in .org format makes for very low friction sharing. Org’s auto-adjusting plain-text tables, which supports formulas, is very nice indeed. (I use these for fx calculation on my invoices, since I invoice in EUR but usually incur expenses in GBP.)

            1. 1

              Org-Babel? If there was a good external tool for Babel, (maybe there is?) I would definitely use it for playbooks and stuff.

              1. 1

                Emacs can be invoked from a script, which might help? Take for example this org file, let’s call it foo.org:

                Lorem ipsum ...
                #+BEGIN_SRC sh :tangle hello.sh :shebang #!/bin/sh
                echo "Hello World!"
                And another old trooper here:
                #+BEGIN_SRC python :tangle goodbye.py :shebang #!/usr/bin/python
                print "Goodbye, World!"

                Now, if you run the following command, it should create two files hello.sh and goodbye.py in the current directory.

                emacs --batch --find-file foo.org --funcall org-babel-tangle

                That will spit out some diagnostics, but importantly you’ll have:

                $ cat goodbye.py 
                print "Goodbye, World!"


                $ cat hello.sh 
                echo "Hello World!"

                This works for me on Emacs 24 and 25, but not in the ancient Emacs 22 that comes by default on OS X.