- Customers often say the docs are hard to navigate
- Cannot find what they need quickly - instance JSON, endpoints, auth can be confusing
- Want ability to search for Element specific docs
- Want link to endpoint's API docs as well
- Feeback regarding experience has been negative
- Greg's content may be too verbose on some items - Create Instance
- As Producer/Owner of Documentation Content I feel responsible for experience
- Want to deliver a great dev experience as our success depends on our docs (not entirely, but a large portion)
- Cannot write the JS needed for the docs app (Phil's App)
- Am able to do some debugging, but cannot write the code
- Something breaks, am reliant on Phil to fix
- Right now any Element in general or 'new hub' doesn't show up in the docs app
- Sales is sending links to docs - when link is opened, menu doesn't expand to show current location
- received negative feedback from this
- Want the means to problem solve without Phil's help as he is over allocated
- Past iterations of docs did not meet our customer's needs
- We have a lot of documentation
- Docs going to continue to grow
- Discovered Jekyll via Rocky
- Feel confident that I can manage it without Phil's help
- Possible Perks
- Can use GitHub flow
- Can compose content in Markdown
- Layout is Bootstrap, devs said they are familar with BS
- Other devs can contribute
- Code can be hosted on GitHub for free
- To update, create pull request - devs familiar with process
- Get experience learning a new app/system
My intent was to try and come up with a solution that I could manage, would scale, and require minimal time from Phil. Wanted to take the initiative on this and iterate our way to success. I did not mean for it to become another thing we have to manage. I think we can build a great dev experience and it would not become another chore.
The site would be built using Jekyll, a static website builder http://jekyllrb.com/. Files are written in Markdown and rendered via html css.
The code would be hosted on GitHub for free. We would use a CNAME to point developers.cloud-elements.com to our GitHub Index page. We would then compile and expose our API documentation using Swagger UI theme Phil discovered https://github.com/jensoleg/swagger-ui. The Element docs would link to the compiled Swagger Docs and be fully searchable.
- Site built using HTMl and CSS
- JS is required to work with the liquid templating language - but Greg is learning and can handle it
- Frees up Phil's time from the app.js maintenance
- All devs can contribute to project - files are in markdown
- project lives in GitHub - devs already know how to branch and create pull requests
- Easily update docs with git push
- GitHub can scale with our needs as we add more documentatiton
- Bootstrap friendly
- Docs will be maintained outside of marketing site
- Atul doesn't want one more system to maitain
- Liquid templating language may feel constrained for some
- Bootstrap friendly - I know not everyone loves Bootstrap
I'm also looking down the road when we open our marketplace and customers begin publishing their own apps.
- How are we going to document them?
- Can we open source this project so they can add docs that way?
- Am I to reach out to all of our customers so I can get endpoint setup info?
- Is that scalable?
To summarize, my intent is to provide a great dev experience that is scalable, throrough, and meets the needs of our customers. If we believe WordPress is the way to, then please let me know. If this idea is a good one, great. If you have another idea, great - let me know and let's get on it. Mark wants to triple, triple, double - we must provide a solid medium for devs to find what they need and move on.