Documentation, right! How and where?

Documentation is something we would (like to) do if there would be time calculated for it in every project. But in a lot of development projects the customer is not interested to pay for something he/she is not going to read at all so where to ‘store’ the application logic?

To my opinion it can help to use the IBM like approach in delivering brief documention in their templates, just like Rocky Oliver talked in his session ‘Creating Maintainable IBM Lotus Notes and Domino Applications – Writing Readable Code’ at Lotusphere 2007.

documentation example

How do you deliver your documentation?

A sample of above can be found here.

Advertisements

3 thoughts on “Documentation, right! How and where?

  1. Gery King 2007-November-10 / 4:43 pm

    Edit history is irrelevant – that’s what a version control system is for. The current version is the only thing that needs to be documented.

    Using tables to layout hidden fields is a waste of time. The name alone should convey eveything you need to know. The UI tells you whether it is computed, Computed for display etc. It tells you it’s type. Don’t repeat yourself…

    The most useful documentation is a thumbnail sketch of how the app works in the ‘About’ document. Everything else should be self-evident. If not put in a comment to explain whatever needs explaination.

  2. quintessens 2007-November-11 / 3:26 pm

    Hej Gery,

    can you explain: “The name alone should convey eveything you need to know. The UI tells you whether it is computed, Computed for display etc. It tells you it’s type” a bit more?

  3. Stephan H. Wissel 2007-November-11 / 6:38 pm

    Don’t put hidden text into tables. The hide-when is executed for every cell. Bette have that in one line. Also don’t state the obvious DocUNID is pretty clear. One very good tip: use IsNotDebug as hide-when formula. Have a computed for display field at the beginning that does compute that value (e.g. by checking an ini value or a role). This way you can check the hidden values when trouble shooting.
    🙂 stw

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s