1

So I started thinking, what is the best practice for publishing generated documentation (e.g. Doxygen, NaturalDocs, etc.) in terms of infrastructure?

I would be generating it through continuous integration:

  • Should it be put in a regular web server?, or should I use something like Sharepoint or some other content publishing software?
  • Should the documentation be available for each build?, or just stable releases
  • Should I put a full copy of each documentation iteration?, or should I put it in version control overwriting itself? (a repository separate to the project code, of course)

For some weird reason I find hard to think that I should just put it in a web enabled server, but this is how I see most do it:

http://docs.spring.io/spring/docs/

However, what happens when your company works on tenths if not hundreds of projects?, most documentation generation tools AFAIK just give you the final HTML output, but it is up to you to manage it.

So, what gives?, is there a better practice/solution than just putting it in the "doc server"?

2

Another way to think of it is not as a "doc server", but that you're building a "Developer Portal" for your API consuming audience. This might include developers, but it could also include product managers, UI/UX folks, business analysts, etc.

Some things a Developer Portal might expose, beyond just raw documentation include:

  • Sample code
  • Sample apps
  • Wrappers / language-specific libraries
  • Tutorials
  • Support forums, ticketing, and other means of contacting the API producers

Stripe's /docs is an excellent example of exposing these kinds of resources along with the documentation: https://stripe.com/docs

Adding these things goes beyond just checking the box of providing docs, to doing the most you can to create a great experience for developers working with your APIs. Think of it as "usability", not in the UI sense, but it what it takes for someone to get up to speed and be successful with your APIs as a product.

1

That's right - document tools that produce HTML should be put on a webserver. If you have many projects, just copy the html output into subdirectories and update a master index page that links to each one. You can put a link to each project's html 'start page' in a wiki for each project (if you use a project management site like redmine or trac).

The point is to create a quick and easy to access link to this documentation. If you put it in sharepoint and make it a downloadable resource that has to be signed-in to and unzipped and then bookmarked by the individual - you can expect to find most people won't bother. If its just another bookmark in their browser, you can expect many people to view it, and getting it viewed is why you do it in the first place.

Personally, I'd keep revisions for old stable versions only. Builds are very transitory, though you will have to keep a "current" or "latest" version that is always overwritten with the current build. If its generated, there's no point in storing the output as well. You could, if you store the binaries just so you don't have to re-generate it, but you only do that for final releases.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.