Wednesday, July 15, 2009

I'm not very good at or about writing documentation. I have some ideas on what I think documentation should be. I think documenting interfaces is more important than documenting implementations. I like documentation systems like Javadoc, since it is right with the code and it allows boilerplate to be automatically generated, and encourages the documentation of interface over implementation.

For external documents, there's often the essential information, and then there's lots of verbiage. I know how to stick in the essential information. I don't know how to generate the verbiage.

Also, where I worked in the past, documents had to be in Microsoft Word format, and were emailed around. I didn't like using Microsoft Word. If I could get away with it, I'd write the documentation in a plain text file using emacs.

Nowadays, the documentation is on Atlassian Confluence, which I greatly prefer over Microsoft Word documents. The Confluence search is horrible, but, other than that, I think it's pretty good. There was an intermediary period where documentation was either in Microsoft Word or in Confluence, or in both, and in discussions on where it should be, I'd always vote for Confluence.

No comments:

Post a Comment