Read the Docs – create, host, and browse documentation
Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. We support webhooks so your docs get built when you commit code. There’s also support for versioning so you can build docs from tags and branches of your code in your repository.
Online documentation system for JavaScript projects that adhere to JSDoc API documentation format. Includes:
Requires Node.js and MySQL.
About a month ago I came across an interesting question over at StackOverflow. Emanuele Minotto was asking if anybody knows of any easy way to integrate PHPDocumentor with GitHub’s wiki. It seemed like a really good idea, so I dug around, but didn’t find anything ready made. PHPDoc’s manual however suggests that things are possible. Unfortunately, I’m too busy currently to get involved in it myself, but I am really glad to see that Emanuele didn’t abandon the idea and started the project at GitHub. If that’s something that you are interested in, I strongly suggest lending a helping hand. I’m sure there are plenty of people who’d welcome this integration.
If you’ve ever had a project without a README file hosted at GitHub, you know the recommendation message to create one. When I first saw that message, I thought it was a bit weird, but, I guess, fine. It never bothered me enough to search for any explanation – I just ignored it, or created a README file. Apparently, there is an explanation – Readme Driven Development by Tom Preston-Werner, one of the GitHub co-founders.
By writing your Readme first you give yourself some pretty significant advantages:
- Most importantly, you’re giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organized or what should be included in the Public API. Remember that feeling when you first started writing automated code tests and realized that you caught all kinds of errors that would have otherwise snuck into your codebase? That’s the exact same feeling you’ll have if you write the Readme for your project before you write the actual code.
- As a byproduct of writing a Readme in order to know what you need to implement, you’ll have a very nice piece of documentation sitting in front of you. You’ll also find that it’s much easier to write this document at the beginning of the project when your excitement and motivation are at their highest. Retroactively writing a Readme is an absolute drag, and you’re sure to miss all kinds of important details when you do so.
- If you’re working with a team of developers you get even more mileage out of your Readme. If everyone else on the team has access to this information before you’ve completed the project, then they can confidently start work on other projects that will interface with your code. Without any sort of defined interface, you have to code in serial or face reimplementing large portions of code.
- It’s a lot simpler to have a discussion based on something written down. It’s easy to talk endlessly and in circles about a problem if nothing is ever put to text. The simple act of writing down a proposed solution means everyone has a concrete idea that can be argued about and iterated upon.
Consider the process of writing the Readme for your project as the true act of creation. This is where all your brilliant ideas should be expressed. This document should stand on its own as a testament to your creativity and expressiveness. The Readme should be the single most important document in your codebase; writing it first is the proper thing to do.