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.
You can get help at mapzen.com/documentation, or click Documentation in the top header on any page on mapzen.com to take you there.
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.
In a repository, files are listed in alphabetical order.
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.
In the help system, we can arrange topics in a specified order in the table of contents. The site also has search and navigation functions, along with custom text styling.
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.
This photo was taken from our office window and reflects our view that open-source documentation is another bridge to the community.
