Mapzen’s commitment to open extends beyond software and data—it includes technical documentation, too. We are pleased to introduce a new part of our website that provides a help system built with open-source tools that displays open-source help files.
Read on to learn how we built the website and how you can contribute to it.
Setting goals for the documentation site
The main goal of the website is to bring together all Mapzen’s documentation in one place. We keep the underlying source help files in GitHub, but display them in a way that is easy to navigate and visually pleasing. In addition, putting the help on mapzen.com connects it to the resources on our website, such as signing up for API keys.
While GitHub is good for storing help files, the contents of a repository is listed by alphabetical order of file names, which may not be the best organization for learning how to use a piece of software. However, with a help system, we can control the table of contents so topics have a readable flow. We can also modify the fonts and source code appearance beyond the defaults on GitHub’s website.
Building the documentation site
After looking at many options for building the help system website, we chose to implement an open-source Python tool called MkDocs to format our GitHub markdown files in to a static, HTML website. MkDocs also creates a table of contents, a simple keyword search, navigation breadcrumbs, and links to move back and forward between topics.
The help site generator repository contains the configuration files and visual themes of the resulting site, if you want to contribute or borrow anything for your own documentation projects. Note that while MkDocs reads just one source, our generator can integrate multiple repositories. Because we have added the help system build process to our continuous integration tools, our internal staging website is updated automatically following a change in the source files. When we are ready to deploy the help updates, we pull the changes into the production branch.
Contributing to the documentation
To encourage contributions from users like you, each help topic has an
Edit this page on GitHub link that points back to the source markdown file. You can then edit a topic and submit a pull request, or add an issue about the content.
We hope that this web site introduces a friendly way of displaying the content and seeing how the topics relate to each other. We’ll be continuing to improve the site’s design and user experience, as well as enhancing the actual content. We’re interested in hearing what you think of Mapzen’s documentation and this website. For example, is the help system easy to navigate, are you able to get started and be productive, and can you find what you need? What tutorials or code samples would help you? Send us feedback or you can log an issue.
Beyond this, if you want to help us write great API documentation and build software demos of our products, Mapzen is looking for a technical writer/developer for our San Francisco office. Send us a note if you’re interested in joining our team.