And this, class, is what we call BLASPHEMIES!!! |
Who are you documenting for?
Set permissions to 'write-only' |
Understanding your audience also impacts how you write your documentation. Speak to the level and with the verbiage which which your consumer is most comfortable. This is similar logic to why we include the user in the standard User Story format.
How will you communicate your documentation?
Documentation is not one-size-fits-all. There are hundreds of ways to document, from wikis to man files to interactive wizards. What format are you going to use to publish your documentation?
Another interpretation of this is where will you put the documentation for your consumers to pull? Most documentation is living, not static, so mediums like email are usually very bad. Do you have a team site, knowledge repository, or some other digital location that your consumers can bookmark to find the latest and greatest? Is the location easy to find and "on the main path", or do they have to dig for it? Make your life easy by making your documentation easy to consume.
What will be done with your documentation?
This is more a corollary for the first two questions. For example, you may think you know who you're documenting for, but what if all they do is file the information away and never look at it? Your audience may not be who you think it is - indeed, your audience may not exist at all.
As for the second question, building a README file to document your smartphone game won't be useful, regardless of how well you know your customer or how accessible you make said file - an in-game tutorial will be much better received.
Bottom line: don't start documenting until you know what your consumers' intended purpose is for the documentation.
Can it be automated?
The first three questions speak more to the elimination or simplification of the documentation you produce. By the time you get to this question, you've determined that the documentation is necessary for your end-user, future maintenance team, or whomever to do what they need with your software. So can this documentation be automated?
Documentation for future development and maintenance is often quite simple to automate. You can use certain comment formatting to generate Javadoc or Sandcastle documentation for Java and .NET applications, respectively. You can use tools to generate your class and sequence diagrams as part of each build. There are several forms of technical documentation that can almost always be automated.
User-facing automation is trickier, but not impossible. For instance, you could generate LaTeX templates that are plugged in with data that's auto-fed to it and output documentation in the format that works best for your users. Get creative with it and see what you can come up with.
Questions?
Those are the questions I've developed over time; what are yours? How do you determine what to document and how? Do you find yourself documenting more or less using Agile than Waterfall? How has the nature of documentation changed? I'd love to learn from your experiences.
No comments:
Post a Comment