Documenting Your Projects With Daux.io

Documenting a project can be a nuisance, but it needn’t be. There are quite a few tools out there to get the job done–I often use Daux.io because of its flexibility.

In this article I’ll show you why you should document, how you can get Daux.io and how you can start using it right now to make your projects much better. 

Why Documentation is Needed

Writing documentation for your project could be the single most important decision you make. The reason this is often overlooked for web-based projects is that there isn’t that much at stake. 

Take a Boeing 787 for example. This product has an extensive body of documentation backing up every aspect from design to maintenance. There’s even a near 150 page manual documenting the 787 characteristics to take into account when planning airports.

Why should an airplane have wide reaching documentation whilst a website doesn’t? 

I believe there are three main reasons: 

• There is a lot more money involved


• Safety concerns 


• Issues of scale

Websites rarely have safety concerns, but as soon as scale or money rears its head you can be sure that documentation will pop up. All large projects such as Twitter and Facebook have staggering amounts of information available for developers, in-house and third party alike. 

Websites which generate a lot of income often also choose to create good documentation. The idea being that if something needs to be altered everyone can refer to the documentation and the website is much less likely to lose money due to loss of uptime. 

Does this mean that you can get by without documentation for a smaller project? Sure it does, the question is: should you? 

The Benefits Of Documentation

Documentation provides a common frame of reference for a project. The benefit of this is pretty obvious when working in a team but it is overlooked when someone is working alone. 

If you make your living building websites, the chances are you build at least a few a year. Will you remember how a website you built in January auto-tweets its content when you come to look at it next August? What if a company asks you to hand over a project to another developer? You may be spending an hour each morning answering questions about your code for the next month. 

Even the most consistent coder is inconsistent. As we grow and learn we tend to alter the way we work. Perhaps you’ve introduced a build tool like Gulp into your workflow, perhaps you’ve started using object oriented PHP. 

Documentation can also explain situations which aren’t obvious in the code itself. You may have chosen a sub-par solution on purpose, simply because you were asked to do something quickly and the end justified the means. This can be added to the documentation, perhaps as a task to upgrade later. 

Documentating With Daux.io

Daux.io may scare some people at first because it isn’t just simple HTML, it can only be previewed using a server. However, setting it all up is quite straightforward and once you jump that hurdle, usage is easy and flexible. 

Getting Daux.io

The easiest way to get Daux.io is to download it from Github. You can download the package using the Download ZIP button on the right sidebar. If you’re an experienced Github user you can clone it, or you can even grab it from Packagist via composer.

If you download from Github you should end up with a folder named “daux.io-master”. 

Rename this to “documentation” and move it to your desktop for clarity’s sake. To write your documentation you actually don’t need anything. You can edit the Markdown files in any editor and use a command to convert it all to HTML for easy sharing. However, it’s best to preview our work as we go along, so we’ll do some preparation for that.

Previewing Documentation

To preview the docs we’ll need a server. Luckily, everything is provided within the Daux.io project folder, we just need the pre-requisites to run the server: npm and Grunt. 

Installing npm and Grunt

The easiest way to grab npm (Node Package Manager) is to install Node. Go to the Node website and download the installer. Once installed you should be able to use the npm command in the terminal (on Linux/OS X) or in the command prompt (Windows).

Quick note: I will be referring to the command prompt on Windows and the terminal on Linux/OS X with the same word: terminal. 

The next thing you’ll need is Grunt. Grunt is actually installed via npm so if you’ve already completed the last step it should be super simple. Open the terminal and type the following command:

npm install -g grunt-cli

You now have the base tools needed to get started. If you’re new to npm I highly recommend learning more about it. It allows you to install tools easily and you don’t necessarily need to know Node.js to use tools the work with npm (like Grunt). 

Everything up until this point is only needed if you don’t already have these tools installed. No matter how many instances of Daux.io documentations you have around, you won’t have to do this again.

Tip: learn more about command line tools by following the beginner’s series The Command Line for Web Design by Kezz Bracey.

Windows Users: Installing PHP

This step is only for Windows users, OS X and most Linux distributions come with PHP pre-installed so if you’re on those platforms you can skip this section. Unfortunately installing the PHP command line in Windows is a bit of a hassle, here’s the run down. 

Head on over to the PHP downloads page and grab the version of PHP you would like. I used the “VC11 x86 Non Thread Safe” version when testing. I downloaded and extracted this archive to my root folder, C:/ and renamed the resulting folder to “php”. At the end of the process you should have a folder named “php” in your main C:/ directory, the folder should contain a “php.exe” somewhere. 

Next, we’ll need to make sure the PHP command can be run from anywhere. On Windows 7, the simplest way to do this is to go to the start menu, right click on Computer and select Properties. Click on Advanced System Settings in the left sidebar. Click on the Advanced tab, then on the Environment Variables button at the bottom. 

You’ll need to click on path in the top pane and then edit. At the very end of the value add a folder reference, something like this: “C:\Users\Dani\environment”. This should be a folder within your own user folder. Once done, save everything and create this folder. (If you use a different version of Windows take a look on Computerhope, it lists how to do this on multiple versions). 

Inside this folder create a file named “phppath.cmd”. Edit this file using any text editor and add the following content: 

PATH=%PATH%;C:\Users\Dani\environment
php -v

Once done, navigate into this folder via the command prompt by typing cd %userprofile%/environment and run the following command: phppath.

Finally, close the command prompt and reopen it, php should now be available globally. Again, this is something you only need to do once, and only on Windows. 

Setting Up Daux.io

Still in your terminal, navigate to the project folder. Remember, this should be on our desktop at this stage. On Windows you can use the following command to get to the project folder:

cd %userprofile%/Desktop/documentation

On OS X you can use the following command:

cd ~/Desktop/documentation

The first command you should issue is npm install. Once that has completed run npm update to make sure everything is up to date. These commands install and update all the dependencies of Daux.io. You will need to do this for each instance of Daux.io you have.

Running The Preview

We’re finally ready to preview our documentation. This is now a matter of one command, all you need to do is type grunt into the terminal (make sure you are in the documentation folder when issuing the command).

After a few seconds of thinking you should see something like this: 

This means that the server is up and running, a new tab may already have opened in your browser. If it hasn’t, take a look at the IP shown next to “Listening on” in the terminal and enter that into your browser. In my example this IP is “127.0.0.1:8085”. 

Note: in some cases the tab opens but shows “no page found” or some similar error. In this case reload the tab after a couple of seconds, the server may need a bit more time to initialize.

You should now see the default documentation provided in the browser. The view you are seeing is generated ad-hoc from the documentation Markdown files. Now that we can see what we’re doing, let’s look at writing documentation. 

Writing Documentation

Within the “documentation” folder you should see a “docs” folder. This contains your actual documentation, everything else is for Daux.io to do its magic. Daux.io uses a specific naming convention to give you full control over the order of pages. 

Each item in this page should start with a number and an underscore. The higher the number the lower down the page will be in the documentation. If you need a single page create a Markdown file (eg: 04_Updating_Plugins), if you need a hierarchical structure of pages create a folder (eg: 05_Code_Styling). 

The text after the number determines the name of the page in the documentation. My previous examples will become “Updating Plugins” and “Code Styling”. Be sure to use only alfanumeric characters and underscores, underscores will be converted to spaces.

From here on out it’s smooth sailing, all you need to do is edit your files in Markdown’s style. If you aren’t familiar with markdown take a look at the Markdown Cheatsheet. It’s essentially a way to mark up text (indicate headings, links, images, etc.) without HTML code. 

If you’re creating a section with sub-pages using a folder you can specify sub-pages in the same way as before. Within the created folder create individual files starting the file name with a number (which gives the page its order) and the name you’d like displayed. 

Landing Pages

One other neat thing Daux.io allows you to do is create a landing page for your sections. Your whole documentation can get a landing page if you create an "_index.md" file. Take a look at the default example to get a feel for the formatting.

Each section can also have a landing page. If a section doesn’t have a landing page the top level menu item doesn’t click through to anywhere, it just opens up the sub-section list. If you’d like the top-level entry to have its own page, create an “index.md” file within the folder for the section.

Managing Multiple Documentations

Some projects may require multiple documentations. A website may warrant an end-user documentation and a developer documentation which would contain wildly different information. 

One way to manage multiple documentation needs such as this is to create multiple instances of Daux.io. This however requires you to run the server separately and set some things up again. Luckily there’s a better way! 

Take a look at the “global.json” file in the main documentation folder. If you open this with your text editor you should see that the docs_directory parameter is set to docs.  Create a copy of the docs directory, name it “user_docs” and add some different dummy files to it to be able to tell it apart from the original documentation. 

Now change the docs_directory parameter to user_docs and reload the documentation in your browser. You are now viewing the contents of the new folder. This makes it easy to switch back and forth between documentations on the fly, without having to reboot the server or use a different instance of Daux.io.

Generating Final Documentation

Of course at the end of the day we need to distribute our documentation. This is best done in HTML form and Daux.io has us covered! In the terminal, while in your documentation’s main directory run the following command:

php generate.php

This will create a “static” folder with all the HTML files and assets needed to view the documentation. You can zip this folder up and send it to someone or upload it to a server and link to it. 

Advanced Project Setup

There are a bunch of things you can control via the "default.json" file. By default there will be a Made by Todaymade link in the sidebar along with some Twitter follow links you either don’t need or want to customize to your project. The Daux.io main page lists the options you can use under “Configuration” further down the page. or just refer to the “default.json” file.

You can use "twitter": ["yourtwittername"] to add your own Twitter link for example. Links can be controlled using the links parameter, here’s how to add a couple: 

"links": {
    "GitHub Repo": "https://github.com/yourgithubrepo",
    "Support": "https://support.myproduct.com",
    "Made by Me": "https://mywebsite.com"
}

You can find all the options on the Daux.io main page. Here’s an example of a full "default.json" file for an imaginary project.

{
    "title": "My Project",
    "tagline": "My Stylish Documentation",
    "docs_directory": "docs",
    "valid_markdown_extensions": ["md", "markdown"],
    "repo": "danielpataki/exampleproject",
    "twitter": ["danielpataki"],
    "theme": "daux-blue",
    "breadcrumbs": false,
    "template": "default",
    "clean_urls": false,
    "toggle_code": false,
    "date_modified": false,
    "float": false,
    "links": {
        "GitHub Repo": "https://github.com/danielpataki/exampleproject",
        "Support": "https://support.exampleproject.com",
        "Made by Daniel": "https://danielpataki.com"
    }
}

Conclusion

Setting up Daux.io may look like a daunting task at first, but it isn’t that lengthy, especially on Mac/Linux systems where most of what we need is pre-installed. If you’re not used to the terminal and local servers it may take a little while to get used to the environment but doing so will pay off tenfold.

Once you get up and running with Daux.io you will find that it is easy to use, flexible and easy to maintain. Your project, your client, your co-workers and your project’s end users will all thank you for your efforts and hopefully your time spent supporting the project will be minimized.