Docs are (sad to say) often a point of last resort for a reader who’s already frustrated and cranky over failing to figure out the answer through trial and error, so any additional barriers to them getting at the information they need will not go down well. If more than one person writes your documentation, a style guide is a must to ensure that your end reader feels comfortable with and confident in your documentation. Continue reading “Style Guides”
Category: Writing
As simple as possible…
Over-simplification is an issue that bothers me. I sometimes need SMEs to explain a new field/concept to me in excruciating detail so that I understand it well enough to start writing about it, but I don’t always include the same level of detail in what I write, because I know/expect that the intended audience is starting from a greater level of understanding than I did.
Wikiquote suggests that “Make things as simple as possible, but not simpler”, a quote popularly attributed to Einstein, is itself a simplification of “It can scarcely be denied that the supreme goal of all theory is to make the irreducible basic elements as simple and as few as possible without having to surrender the adequate representation of a single datum of experience.”
The simplified version may be snappier and more user-friendly for most of us today, but the original, which appears in Einstein’s 1933 Herbert Spencer Lecture “On the Method of Theoretical Physics”, was simple enough for the intended audience. And that’s kind of the point.
Continue reading “As simple as possible…”Writing and Formatting Headings
Documentation users rely on headings to quickly locate content of interest, so they should be easily identifiable and provide meaningful context/keywords in a consistent way. Within these golden rules, though, there’s ample room for customisation to reinforce a particular document/provider’s brand. Continue reading “Writing and Formatting Headings”
Doc tools: Overleaf
I’ve been working a lot with LaTeX this year. On my laptop, my preferred toolset is WinEdt and MikTeX, but I’m intrigued by the more portable looking solution of Overleaf.
Overleaf is a web-based LaTeX editor that allows you to store and edit your content in the cloud. You can sign up for a free account if you won’t be using it much, or a monthly subscription to add more projects plus a few extra features.
The site has a good catalog of existing templates you can choose from to start a document, article, presentation, CV, or whatever. They even provide an interactive tutorial to get you up to speed if you’re not too familiar with LaTeX. More advanced users can upload whatever custom/specialised templates and resources they need.
The split-view, web-based editor shows your editable markup on the left hand side, and a dynamic preview of the results on the right hand side. As I’m writing this, there’s a beta RichText view of the sources which shows a bit of a mashup of WYSIWYG and source content depending on which document I’m looking at – I guess it renders what it can parse sufficiently and leaves the rest in its raw format.
The free plan has a limited number of files per project (60), and an overall space limit of 1GB, but you can have as many projects as you like within those constraints, and get almost all the bells and whistles. Also, as seems to be a trend with many cloud-based services, they offer bonus space and features in return for social media interactions, inviting friends, and the like.
If you’re looking for a collaborative/cloud-based solution for your LaTeX project, you’ve little to lose by taking Overleaf for a test drive.
59 Second Grammar Lessons
I’m a big fan of Richard Wiseman’s: he’s a clever chap, and it’s worth dipping into his books or YouTube videos if you’ve a gap in your to-read/to-watch list. Recently, he’s added a few videos on grammar to his In 59 Seconds YouTube channel — each is a cute mnemonic with a quiz at the end to reinforce the concept. Here’s a quick round up of what’s there so far; hopefully there’s more to come. 🙂 Enjoy!