Designing the Documentation for a Developer Product

We recently shipped the new design for the Codeship Documentation. Apart from bringing it in line with the new design of our website, we had a few other goals with this redesign. Our main goal was to make sure you don’t spend much time on there. Search, find what you are looking for and get back to what you were working on! This required a clean, readable layout, an easy-to-reach search function and, of course, good content.

Use the Search, Luke!

The new design features a very prominent search bar. This allows you to get information as quickly as possible because you immediately can get to any page within the documentation no matter where you are currently located.

No Distractions

When you’re consulting the documentation you have a question you want an answer to. And as mentioned above: You want to find it fast. We made the individual content pages distraction free. There are no unnecessary elements on the page, with the main focus being the content itself.

We made sure to strongly emphasize how we display the content itself by providing a clean and easy-to-read layout. In cases where we thought our blog was a better fit, we moved content there. A good example are the videos from our Deployment Academy that show in detail how to set up Continuous Delivery with Codeship.

Open Source Documentation

Our documentation is open source. The source code is available on our Github repository and you’re free to fork it and contribute to it. This doesn’t mean we want you to maintain our documentation. If you think a page needs restructuring though, or we are missing some content, you can simply open a new issue and we’ll fix it for you. Of course, if you feel like solving things yourself, you can open a pull request and we’ll send you some awesome Codeship Stickers.

Technology

The technology is pretty basic. It’s a simple Jekyll installation with some plugins to make our lives easier. The site gets built by Codeship (of course) and then pushed onto S3 for your viewing pleasure.

What's next

For Developer Products like Codeship, a well designed, extensive documentation is important. We want to make sure you get the answers to your questions as quickly and conveniently as possible. Rest assured that the redesign was only the first step and we are not going to stop there. As my primary responsibility at Codeship is Support I learn a lot about the questions you have. I will use these learnings to further improve our documentation so you can access the information you need any time.

Do you know of an article that needs my attention? Tell me on Twitter!I also would love to learn what you think about our new Documentation in the Comments section!

P.S.: If you didn’t already visit the new documentation, go check it out now!P.P.S.: A big shoutout to the guys at SendGrid. Their documentation setup and list of plugins were a great inspiration and help!