Joe Conley Tagged javascript Random thoughts on technology, books, golf, and everything else that interests me http://www.josephpconley.com/name/javascript Graph-Based Documentation <p>Has anyone ever met a documentation system they both <em>liked</em> and found <em>useful</em>? I love Evernote as much as the next guy but the simple list view has its limitations. Most wikis present information in a tree view where pages are restricted to a parent-child relationship. Neither are very useful or intuitive for documenting complex systems!</p> <p><img src="https://confluence.atlassian.com/download/attachments/218270144/Confluence%20Tree%20View%20Web%20Part.PNG?version=1&amp;modificationDate=1192642298936&amp;api=v2" /><br /></p> <p>I’m a very visual thinker. I know from experience that when dealing with several layers of abstraction, having a good visualization can be very helpful. And when I say <strong>good</strong>, I mean <strong>good</strong> in the sense that the visualization is <strong>as close to reality as possible</strong>. Shane Parrish and others remind us that <a href="https://www.farnamstreetblog.com/2015/11/map-and-territory/">the map is not the territory</a>, but we can get pretty damn close. And I think graphs can help (<a href="https://neo4j.com/blog/technical-documentation-graph/">so does neo4j, shockingly</a>). Because it’s 2017, and we deserve more optimal ways to visualize ideas and systems.</p> <p>Why graphs? Graphs are inherently simple. There are nodes and edges. That’s it. Nodes represent a “thing”, edges represent a “relationship between things”. There’s no parent-child restriction; any node can be related to any other node. Visually, the relationships can be shown compactly and the information structure is more flexible. Using this as our foundation, we can start to build something useful.</p> <p>So, here’s what I’ve got so far. I’m calling it <em>Episteme</em> (from the Greek for <a href="https://en.wikipedia.org/wiki/Episteme">“knowledge, science, or understanding”</a>). It’s a desktop app powered by <a href="https://electron.atom.io/">Electron</a> and is a simple graph of nodes and edges where nodes are some entity we want to document. Here’s an example based on my current <a href="http://www.swingstats.com/about">SwingStats</a> architecture:</p> <p><img src="/assets/episteme-graph.png" alt="Episteme Graph" /><br /></p> <p>Here the nodes represent backend services, webapps, datasources, and APIs while the edges connect the nodes that interact in some way. Clicking on each node will bring up a Markdown-based document which will autosave on edit:</p> <p><img src="/assets/episteme-node.png" alt="Episteme Node" /><br /></p> <p>I’ve already been using it at my current client to help me navigate the dozens of systems and their interactions. I’ve found the most value in quickly accessing common commands (SQL, ssh, docker, etc.), environment information and links. It’s definitely sped up development time as I don’t need to constantly search Confluence or Google for rote memory stuff like query syntax. It just feels like the information is much closer at hand.</p> <p>I’m hoping to add some functionality to make it more context-driven. I think tagging nodes would serve well here, depending on what project/context I’m working on I could filter the graph by tags to only show relevant nodes. As the graph grows, having a “Jump To” button for nodes would be nice. Full-text search is probably inevitable too.</p> <p>Another interesting extension would be having teams share and collaborate on the graph. Maybe in a Git-based system with a fork/clone model so you get version control for free and can see how the graph evolves over time? Throw in some live documentation a la <a href="http://swagger.io/">Swagger</a> and baby you’ve got a stew going!</p> <iframe width="560" height="315" src="https://www.youtube.com/embed/Sr2PlqXw03Y" frameborder="0" allowfullscreen=""></iframe> <p><br /></p> <p>One cool thing to note is it took me five hours to get a useful protoype working, and most of that time was spent learning Electron.<br /> I’ve spent a few more hours on refinements but <a href="http://visjs.org/">vis.js</a> and <a href="https://simplemde.com/">SimpleMDE</a> do all the heavy lifting, and the graph is persisted as a simple JSON file for now. And I’m not a master front-end developer by any stretch of the imagination so if you have an idea, find some good tools that get you most of the way there and kick the tires!</p> <p>Interested in this stuff? Wanna see a hosted version so you can take it for a spin? Wanna help me finish building the damn thing? Let me know in the comments below or on Twitter <a href="https://www.twitter.com/josephpconley">@josephpconley</a>. And thanks to those five brave individuals who voted in my <a href="https://twitter.com/josephpconley/status/852576703419478016">Twitter poll</a>, your feedback is much appreciated!</p> Wed, 26 Apr 2017 00:00:00 +0000 http://www.josephpconley.com/2017/04/26/graph-based-documentation.html http://www.josephpconley.com/2017/04/26/graph-based-documentation.html Build responsive webapps using total.js and Knockout.js <p>I’ve recently spent time evaluating the myriad universe of <a href="http://nodejs.org/">Node.js</a> web frameworks. My motivation was twofold: to get acquainted with the increasingly popular Javscript server-side technologies, and learn a simple framework wherein I could quickly build a reasonably complex web application. As my search wore on, the following criteria for such a framework began to emerge</p> <ol> <li>Convention over configuration (i.e. reasonable MVC patterns, routing, etc.)</li> <li>Integrates easily with other libraries/good framework utilities</li> <li>Wealth of practical examples</li> </ol> <p>After spending much time traversing the impassioned treatises of StackOverflow and consulting the hallowed counsel of the ThoughtworksRadar, I have found the simplicity of the <a href="http://www.totaljs.com/">total.js framework</a> most appealing.</p> <table class="image"> <tr><td><a href="http://www.totaljs.com" target="_blank"><img src="/assets/totaljs-logo.png" alt="total.js logo" /></a></td></tr> </table> <p> <br /></p> <h2 id="criteria">Criteria</h2> <h3 id="sensible-conventions">Sensible conventions</h3> <p>Total.js follows the model-view-controller convention to much success. Simply place the relevant code in models/views/controllers folders and you’re good to go. In addition, the routing is very simple to wire up, requiring a simple declaration mapping each route to a Javascript function. Here’s an example of a typicaly RESTful routing situation:</p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>exports.install = function(framework) { framework.route('/users', listUsers) framework.route('/users', addUser, ['post']) framework.route('/users/{id}' updateUser, ['put']) framework.route('/users/{id}' deleteUser, ['delete']) }; function listUsers(){} function addUser(){} function updateUser(id){} function deleteUser(id){} </code></pre></div></div> <h3 id="plays-well-with-others">Plays well with others</h3> <p>Total.js enjoys all the benefits of any Node.js framework, namely access to the treasure trove of libraries in <code class="highlighter-rouge">npm</code>. However, I was pleasantly surprised to find a <a href="https://docs.totaljs.com/latest/en.html#api~Framework">sizeable collection of built-in utlities</a> to manage common web application functionality like file operations, email, and websocket administration. There is also the option to build your own modules by writing custom code which can hook into different events in the web application lifecycle. Total.js <a href="https://github.com/totaljs/modules">has already built a list of modules</a> to get you started.</p> <h3 id="examples">Examples</h3> <p>One potential drawback here is the relatively small size of collaboration/interest in this framework as of now (try googling a nontrivial issue), but overall I’ve found that the wealth of examples provided in <a href="https://github.com/totaljs/examples">totaljs examples</a> answered most if not all of my questions.</p> <h2 id="obligatory-todo-app">Obligatory TODO App</h2> <table class="image"> <tr><td><a href="http://www.knockoutjs.com" target="_blank"><img src="/assets/ko-logo.png" alt="Knockout.js logo" /></a></td></tr> </table> <p> <br /></p> <p>As I evaluated Node.js frameworks, I noted that the most popular example app was the TODO application. In that spirit, I’ve created a <a href="https://github.com/totaljs/examples/tree/master/knockoutjs-todo">basic TODO app using total.js and Knockout.js</a>. This app took roughly 20 minutes to build, and most of that time was spent refreshing my memory on knockout.js data-binding syntax.</p> <h2 id="caveats">Caveats</h2> <p>Total.js minifies html/cs/jss by default, so debugging javascript is nigh impossible if you write javascript code in <code class="highlighter-rouge">&lt;script&gt;</code> tags in your html. If you plan on doing significant Knockout.js development, I’d highly recommend keeping all viewmodel code in a separate Javascript file, and setting the js-minify flag in your config-debug file to false.</p> <h2 id="conclusion">Conclusion</h2> <p>There’s no lack of Javascript web frameworks, and like any technology toolbox it’s important to use the right tool for the job. While I’ve only just scratched the surface of the framework, I would highly recommend total.js to beginners and experts alike.</p> Wed, 18 Jun 2014 00:00:00 +0000 http://www.josephpconley.com/2014/06/18/totaljs-knockoutjs.html http://www.josephpconley.com/2014/06/18/totaljs-knockoutjs.html