I have written about my love for plaintext before.
Here I'm going to show how to get good at using plain text when writing specifications - in particular, specifications for software designs. We're going to cover some basic scenarios and the tools and approaches that have worked well in my experience.
Here are some of the typical activities that you'll engage in.
My tools of choice to start with are emacs and VS Code. Out of the box, you can get a very good experience with either one of them.
But with so many modes and plugins and options, what's a good way to set yourself up for success? What are the best bits you can use for software design specs?
Authoring is the meat and potatoes of working with a spec. Edits are a variation on authoring, and early research for design specs is often a messier version with lots of links, ideas, TODO items about things to go learn or decisions to make, but without a focus on explaining things clearly to another audience.
For private notes, there is often less need for good, pervasive tooling - whatever gets the job done will do. I'm a bit of a fan of outline in emacs, which was my original information organizing mode. It's quite a bit faster than orgmode, but of course it has a lot fewer features.
orgmode is a powerhouse and can do everything under the sun with the right setup. However I often combine emacs and VS code, and VS code doesn't have very good support for many of those extra features.
Again, because I often switch between emacs and VS code, I tend to gravitate to things that work well across both. These days I'm relying more and more on markdown files, which has the added benefit of allowing more people to read specs, as they are nicely formatted in browsers in many contexts.
For emacs, markdown-mode has you covered. You can even use inline images, although I don't think I've done that (again, I strongly favor plain text for work).
Here are the major things I typically care about when writing specs.
If you follow the recommendations above, you'll get a text description of diagrams, typically with very little concern for formatting. I love me some content.
However, you'll find yourself wanting to include more visual diagrams sometimes, especially for reviews or to help understand some flows better.
I'm going to give a low-tech solution here that should work well with out of the box configurations, without having to get your colleges to do anything special.
For GraphViz-based diagrams:
foo.md, create a foo-diagram.gv file (or multiple files if needed).foo-diagram.gv file. Your best choices are either an .svg file (which is vector and text-based and thus should result in something that plays nice with any versioning tool), or a .jpg file (which won't version as well, but has better broader support in previewers).For sequence diagrams:
foo.md, create a foo-sequences.md file.foo-sequences.md file, and use an inline code block with sequence language.foo.md spec in a code block to preserve formatting.If all else fails, you can always include a binary file. But why would you if you can help it?
How to conduct reviews? There are two main tools I've used for this.
There are a many benefits to tracking your documents in plain text: easy to keep text with code, maintain history of changes, branch for proposals, etc.
Any version control system will do, and one of the most popular ones these days is git. You can set up a local repo for your own usage, sketch out multiple variations locally before sharing, and leverage all the tools that support this in an integrated manner.
VS Code ships with Git support, so you don't really have to do anything to have this light up within the editor.
Within emacs, magit is very easy to use and set up, has a ton of commands a keystroke away, and an excellent menu system with help to guide you throught common and uncommon operations.
One formatting tip: markdown won't care if you have line breaks or not, but your diff tool will. Don't forget to break your lines every now and again. For example, after every sentence or every other sentence. That still allows you to format paragraphs at whatever length is reasonable, but it'll be easier to review changes over time.
One of the nice things of plaintext is that there are so many tools that can help with searching. For local searches, a simple findstr works just fine most of the time. Of course editors have their built-in commands.
And once you're in a proper source repository with a decent frontend, your files end up indexed, so for example GitHub will find your content just fine.
Happy spec'ing!