Designing the Documentation for a Developer Product

Codeship NewsIndustry

Reading Time: 3 minutes

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.

Sign up for a free Codeship Account

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!

Subscribe via Email

Over 60,000 people from companies like Netflix, Apple, Spotify and O'Reilly are reading our articles.
Subscribe to receive a weekly newsletter with articles around Continuous Integration, Docker, and software development best practices.



We promise that we won't spam you. You can unsubscribe any time.

Join the Discussion

Leave us some comments on what you think about this topic or if you like to add something.

  • Anton Gogolev

    Beautiful stuff! That “Rig” thing you mentioned in the slides — is it available anywhere?

    • Roman Kuba

      Hi, thx for the interest in the Framework. We are actually in the process of Open-Sourcing it. You’ll find it here: https://github.com/codeship/RIG
      I’m planning to release the first packages (i.e. the Grid System) this week. Feel free to watch the repository and be the first to know when things go online ;)

  • Tristan Bailey

    I like the clear writing and short line length makes it less tiring to read long pages. But I like having a side bar in documentation. I dont like relying on search but good search is a help. If you rely on search it feels more like customer service section hiding millions of q and a and keeping you from a good indexed result.
    Search also makes it hard to keep a mental picture of where the reference you were looking for was. Hard to work through all the pages to have learnt all you can.

    Large images or space at the top of a page used for reference also makes me feel tired as it steals space before the reference first line and means I will be scrolling more if having it open on the side of the screen while I follow it. The page is good for being responsive as you dont loose page space on the small screen though, but the header does not get shorter.

    So nice clean start but consider adding back a side menu even if it expands in, as more avenues to reference are good for learning, if they keep out the way.

    • Ahoy Tristan,

      thanks for the long and thoughtful comment. You raise some valid points and we will constantly improve the documentation pages, both by adding new content, as well as by improving usability and fine tuning the layout.

      You’re right, hiding the navigation and relying on search completely hides the actual amount of content available. I like working with search, but I’m an avid http://www.alfredapp.com user as well. ;) We currently list the top 4 articles from each section at the main page and provide links to a full listing, but this might not be enough. We are keeping track of how users are interacting with the site and will adjust accordingly.

      As for the header image at the top, I was already thinking about ways to reclaim that screen space on content pages, without dropping the prominent placement of the search bar. Maybe we’ll move it to the header or find another solution. But especially on smaller screens this large image has bothered me as well.

      So, thanks again for the kind words and I promise you we’ll continue to work on our documentation and improve it over time!

      Cheers,
      Marko

      • Tristan Bailey

        Thanks Marco, CodeShip is a great product and I think manuals are an area most of us spend enough time writing or designing, so solutions are not as clear always.

  • Amit Das

    Nice take but I was expecting a bit more exhaustive explanation on the process. For example,
    – How did you collect all the modules that will go into a documentation page detail and how did you frame the information architecture around it?
    – What is usually the workflow of the entire documentation? How does one take comments from a dev file and merge it into the template? What’s the design pattern followed there?
    – If there are dedicated content writers for the docs, how do they use the internal product? Is that designed enough for their ease of use and easy preview of edits and modifications?

    I’d appreciate and love if you can put more light into the meaty part of the stuff as well. :)