Inspiration
When working on What She Really Said, I had trouble navigating the documentation of the various Atlassian repositories (https://bitbucket.org/atlassianlabs/ac-node/, https://bitbucket.org/atlassianlabs/ac-koa/, https://bitbucket.org/atlassianlabs/ac-koa-hipchat, et al) as the information was divided between READMEs, the Wiki, and links to the developer portal. While it might not seem important, I think good documentation is critical for a nice developer experience and I knew there had to be a better way to display documentation for BitBucket repositories.
What it does
This add-on allows you to embed your documentation within your BitBucket repository. It can display any sort of rich text documentation whether it be generated from documentation generators like Sphinx/RubyDoc/JavaDoc, etc or whether it is a website like the Atlassian Developer Portal or a playground like CodePen or Golang playground. This can help teams curate documentation to their developers easily in a manner that makes it easier for them to make sense of it all.
How I built it
I used the Atlassian Connect Express project starter (with much inspiration from https://bitbucket.org/tpettersen/bitbucket-git-guilt). Deployed to Heroku for painless hosting.
Challenges I ran into
Ironically, the challenges I ran into were mostly related to missing and/or insufficient documentation. While I understand these APIs are not set in stone and there a lot of ongoing, parallel experimentally repositories toying around with various Atlassian products, it ultimately results in a confusing experience for a new developer.
Accomplishments that I'm proud of
Shipping something that I hope will help with a common problem developers face. It's one good thing to have a good, stable API, but it's nothing without helpful, excellent documentation.
What's next for Documentation for BitBucket
Right now the docs page is served from an external site. What I'd like to implement in the future is have the option of serving the docs in the repo from a sub directory directly from the BitBucket raw files endpoint (with a proxy server to include the correct mime-type, something like https://rawgit.com/). If the docs are within the repo, it'll also help with contributions to the docs and lead to a better (update code → update docs) cycle that is crucial for great documentation.
Log in or sign up for Devpost to join the conversation.