Tag: writing

The Missing Pieces: What Online Tutorials and Docs Always Seem to Forget

Yo, fellow coders and tech enthusiasts! Adron here, and today we’re diving into a topic that’s been grinding my gears for ages – the stuff that’s always missing from online tutorials and docs. Buckle up, ’cause we’re about to get grumpy!

0. The Invisible Prerequisites

Before we even get to the main course, let’s talk about the appetizer that so many tutorials forget to serve – the damn prerequisites! I can’t tell you how many times I’ve started a tutorial only to find out halfway through that I needed some obscure tool or specific version of something that wasn’t mentioned upfront.

Here’s the deal, tutorial writers: lay out ALL the prerequisites clearly at the beginning. And I mean ALL of them. Don’t assume I have jq installed for your GraphQL tutorial. Don’t assume I’m running the latest version of Python (and for the love of code, specify WHICH Python – 2.x or 3.x?).

And here’s a novel idea: how about actually telling me where to find and install these prerequisites? Give me links, give me version numbers, give me command line instructions. Assume I’m starting from scratch on a fresh machine. Because guess what? Sometimes I am!

Even though this isn’t a tutorial, but just because I mentioned them here, check out jq here and Python here.

Continue reading “The Missing Pieces: What Online Tutorials and Docs Always Seem to Forget” →

My Review of JetBrains’ Writerside ✅ or ❎ ?

Alright folks, let’s dive into the latest concoction from the JetBrains‘ lab – Writerside. This isn’t just another tool; it’s a game-changer in the technical writing arena. Buckle up as we take a tour of this nifty piece of tech wizardry.

The Gist of Writerside

Melding Code and Prose

JetBrains has pulled a rabbit out of their hat with Writerside, built on the IntelliJ platform. It’s like they’ve read the minds of developers and writers, blending their worlds seamlessly. Imagine crafting documentation right in the heart of your IDE – that’s Writerside for you!

Markdown Meets XML

Here’s where it gets spicy. Writerside juggles Markdown and a custom XML-based markup. It’s like having the best of both worlds, letting you switch hats between a Markdown maverick and an XML expert. This duality is a boon for those who want to add a bit more oomph to their docs.

Testing and Styling with Ease

Over 100 built-in tests? Check. Predefined designs that you can tweak? Double-check. Writerside isn’t just about writing; it’s about making sure your documentation is as robust as your code. No more fretting over broken links or layout hassles.

Real-Time Preview and AI Smarts

The live preview feature is like having a co-pilot, instantly showing you the impact of your edits and flagging errors on the fly. And the AI-based spellchecker and grammar tool? That’s the cherry on top, supporting a plethora of languages and keeping your prose polished.

Continue reading “My Review of JetBrains’ Writerside ✅ or ❎ ?” →

Oh the coding stories…

I’ve finally started writing steadily again, after stumbling through more than a few stages of writer’s block. The most recent escapades started with “Quick Start Connections with Terraform and Kubernetes” and “State for Terraform with Google Cloud Storage (GCS)”. But really, there are several types of articles I really need to kick into gear again.

  1. One type of writing is that where I pick apart what’s going on in the industry. This is something I ought to be doing for a number of strategic reasons. Many people should honestly, but it doesn’t happen. We’re often just limited to very specific analysts that may or may not have a solid grasp on what is going on. Since I’m often in the innards of industry projects and efforts, I have some fair insight to apply that isn’t at hands length, it’s from the bloody front lines.
  2. The second type of article is some type of disciplined approach to teach and to learn skills forgotten, skills needed, and hash through things that work into bigger projects.
  3. The third, which is fun and also usually useful are the use case, patterns, and practices articles. I like these, they’re often fun and sometimes even a little controversial.

These all wrap into a steady flow of thoughts, ideas, learning, teaching, and related things. So this is that restart. Against all suggestions to write this type of article, here I’ve done it anyway as a stake in the ground of where I’m officially starting these writing efforts today, Friday the 29th at 8:21pm while at Farley’s Easy in Oakland, California writing while waiting for the arrival of the Coast Starlight. So here’s to writing rhythms and exploring this medium as a medium in which to publish among the mediums! Cheers!

Back From Scandinavia, Back to Project Coding, Writing and Organizing

vikingI just got back from Scandinavia (and Amsterdam). I went for a million reasons, mostly for the adventure of it. Visiting Stockholm, Copenhagen and Reykjavik I saw about a zillion bikes, great architecture, Tivoli, amazing and beautiful waterways, Viking boat building museums, design to die for and so much more. It’s truly one of the amazing areas of the world. But now I’m back in ‘Merica and ready to get back to working on projects, design efforts and all the things I love to do. This blog post is a summary of my immediate return to projects, here’s the list broken into coding, writing and organizing:

Coding

  • Deconstructed – [site] This is the startup I’ve cofounded with Aaron Gray @agray. Check out our main site at Deconstructed. Check out some of the open source projects we’ve started here and listed below.
  • Deconstructed Docs – [site] [JavaScript] [Node.js] I’m using Wintersmith to build docs with static site generation. The docs are located at docs.deconstructed.io. Previous blog entries I did on building a static site with Wintersmith are available at Wintersmith Creating Documentation and Working in -34c, Wintersmith Customization & Github Hosting.
  • Symphonize.js – [site] [JavaScript] [Node.js] [issues] This is a project I started to use configuration as a basis for creating data for any database, but specifically Orchestrate (see blog entries under the writing section I did for Orchestrate). The idea behind this started since I needed something to generate test data for Deconstructed. This one is incomplete, but I’ll be pushing it forward to a deployable NPM Module soon that will be easy to download and just use. There’s also a possibility that this becomes a service that I make available in the near future.
  • Orchestrate.NET – [site] [c#] [issues] I’ve been helping out Robert Smith and a crew to manage the effort around the .NET client driver for Orchestrate. This is currently functional and we’d love anybody and everybody using it to really test it out. Currently I’m using this for the OrchestrateExecute Project listed below too.
  • orchestrate-rapping – [repo] [go] [issues] [group] Yo yo yo, hit the beat. This is an effort that I and others have kicked off to put together a wrapper for Orchestrate’s API. The reason is simple, we want to be able to develop sitting far away from wifi and connectivity, in a park or a cabin in the woods, with a beer in hand and a fire crackling. All while knowing we’re building something that will work when we reconnect to the land of the internet!
  • OrchestrateExecutive – [repo] [c#] [issues] For a very serious enterprise application, I’ve started hacking together a C# Application using Xamarin that will provide a library tier (that could be used as a sample) to use in building to Android, iOS or Windows Phone and all of the native Windows, Linux or OS-X apps that might be needed. In the application I’ll be using Orchestrate and Deconstructed to build out the application. Stay tuned at blog.deconstructed.io for more on this.
  • …and also inspired by Rick Turoczy @turoczy eternally another fucking side project will be going live soon. 😮

Writing

Organizing

  • Bike n’ Hack – Follow @bikenhack for information and more coming soon.
  • Node PDX – More to come on this soon.

…subscribe to the RSS link, hit the e-mail subscription or just ping me or follow me @adron on Twitter and I’ll keep you posted on the goings on of all my efforts and others. Cheers!

Book Writing Notes and Thoughts

I’ve been writing a technical book now since October 1st.  I originally blogged about this with a post of the prospective index.  Since I’ve gotten the first two chapters done and have started on the 6th, 3rd, and 4th.  The reason I am doing these out of order is because of other related items I’ve had to work on related to presentations or the regular 9-5 job.  There are a few things that have hit me while writing the book so far.

  1. The writing for me isn’t all that hard, it’s presenting the how-to parts of the book in a way that work smoothly.  Directions are easy to write up, but making them fit into the larger idea of what is being accomplished is difficult.  Keeping all the steps, screen shots, and other material in order when they’re not in one single document adds to this.  I end up with a chapter directory, a word doc in that, another directory in that for images, and then another directory for edits from the editor and one inside that for final edits back to the editor.  Needless to say it is a growing file structure of stuff.
  2. Jeff Barr wrote in My AWS Book is Now Available! that two things he learned is to set aside time and stay focused and disciplined.  I’m learning that in spite of me already being aware that I needed to be focused and disciplined.  I wanted to set aside time from the beginning but have been hitting a few snags with daily life and community tech events.  I’m getting back on track now, but I’ve been a little behind on some segments.
  3. Be ready to write when you least want to.  It doesn’t matter if you have writer’s block or your head hurts or your drunk, you have to write and get things to progress in a timely manner or things start to unravel.  Be ready when writing a book to crunch late on some nights in order to get things back on track if a derailment occurs.

That’s my book update, for now, back to the writing.