Top to bottom documentation

Hey there again reader, you are the best, the previous reader was quite hasty.

In the last post we have agreed upon the tools required in order to write less and achieve more in terms of documentation.

So far, in most of the cases when I got to work as a consult the documentation was missing altogether or it was composed of some screenshots at best. Usually from the Alpha version when they were used as wireframes, or mockups, or design documents, at this stage the naming makes little difference.

Let’s re-iterate the strengths we we must guide our effort on:

  1. Don’t understand again where you have left the work last time in order to continue. Reading the last phrase is a long enough waste of time.
  2. Document in the dead times of a project, such as waiting for a deploy or a bug fix.
  3. Create re-usable pieces of information
  4. Provide a base for automation

Hmm… yes… sure, fine, might be worth a shot.

As any top to bottom approach we should start with the WBS (Work breakdown structure). We can look at what we have but we don’t know the insides, however, the cover gives us a decent idea on how it might work. SO:

1) Create a blank document and start enlisting the elements you see now on the screen. Just write them, no smart things, we don’t even know what smart things we might have to do.

Good… there, we have a copy of the screen at hand. You can give this copy to any outsource and say “The new version must be the same as the old one”. Done, your screen is ready for a form of outsourcing or retest. Never had this before, nor this freedom. Didn’t take that long either. Yet, a screenshot would have been faster at this point :).

Please perform any sort of action on the screen that has an outcome in the state of the current screen and involves the project’s functionality.

2) Let’s look at the screen. It is very likely that some of the elements are common with the previous screen.

2 a) If there are common elements, stop now. Create a new page on the same level with the first one and move the already present elements there. We will just include them on the second and first page. Done, a bit of work is already done, without even knowing the project.

2 b) If there are no common elements, let’s create a link on the element from the first page to this second one. At this point we still have parity 1:1 with the screenshots if we would name the screenshots with a logic, else, after we forget their order the documentation might prove a bit more handy.

From here on, is just a rinse and repeat isolating common elements until we get to the end of the project.

Being here, if anyone asks you to provide a list of test cases for the UI part of the system, please, just point him to the documentation. If they want a list of functionalities, just follow the flow of the documentation and copy paste. Not that bad for some easy work.

Let’s go further, we know the UI. How about the functionality?

3) Well, find some time. Split your available time in 3. Go to any product owner, producer or management look-a-like team member and ask him what he can explain to you in 1/3 of your time. Use the second 1/3 to ask some questions or take some notes. Use the last 1/3 to add to the proper section that you already have.

Do not go to a developer. The developer will tell you how it works, not how the feature was envisioned. Maybe it wasn’t tested well enough, or never tested.

Rinse and repeat until you cover your project. There, now we have something similar to the exit criteria of the current application. Bits might not match. If they would have the documentation would have been in placed and you would have been hired as a QA.

4) Head towards the page objects automation model and observe that you already have all the bits in places. You know what are the common parts, what are the future test cases and what elements we already have. Even more, comparing the current functionality to the requirements presented on “3)”  we do have some bugs already.

All this with little to no thinking needed.

Hope it help you and pay attention to the italic part, some optimization is required there. Give it a thought.

Leave a Reply

Your email address will not be published. Required fields are marked *