Tag Archives: documentation

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.
Gabi

Object oriented documentation

Hello reader, welcome back, it’s been a while.

Today I have been thinking about the documentation topic. For me, it is a very hot topic.  In the deepest shity moments everyone is saying how good it would have been to have some documentation. Everything lasts until the problem at hand is “hot-fixed” (as this would ever exist).  As soon as the problem is patched and the project is printing money again the voices change to “buhaha, let’s reduce the development time, cut the costs, fuck the documentation”.

I do wonder, still, after a couple of years, how come, exactly the ones that have no skill nor knowledge in approaching the crysis reach this conclusion. You, the hopeless ones should be advocating for proper documentation because it is your CMA ticket in case of emergencies. It is the only proper piece of information you can rely on and share with a team member later in the night from whom you are expecting the problem to be solved.

There is also the management aspect. The business wants things that will be invented tomorrow done yesterday.

Maybe is the development team’s fault. We taught them to be this way. All they have to do is ask and stamp, we will fix it.

Maybe is the product owner’s fault.  With all this agile shenanigan we are not able to tie our shoes properly anymore.

Maybe, maybe, maybe… maybe is nobody’s fault. I’d go for this route. We are all equally guilty for not paying attention to everyone’s need in order to perform better. We all look at that stupid burn down chart and cherish like some teenagers when we go below the line.

I see a solution though. Many years ago, programming has evolved from procedural to object oriented in order to do more in the same amount of time.

I would say that this is a good solution for the documentation. All we need is a platform which allows us to include pieces of documentation from one page to another.

This is necessary because each piece of documentation for each feature is written only once and maintained only once.  I use the excerpt macro a lot at work and it is just the tool needed for the job.

Imagine that you write the documentation for the login feature with all the required tests. The same button is used on the pages 1,3,4,10. All you need to do is use excerpt and done. All the tests and relevant information follow the reader everywhere.

I don’t think I can explain you long enough why this macro or something similar is a must.

Now that we have the tool and the plan, next time I will propose the kind of information that should be written in the first steps of the documentation process. Don’t forget, everyone wants it fast. In order to deliver this we must be able to stop and start in the spare time without having to read again where we have left our train of thoughts.

A while ago I have read that developing happens when the developer writes something new. When the old piece of code has to be read and interpreted it is called maintenance. The world does not have time for that.

I hope this will help you make an idea how the documentation should be written.  In order to get a bigger picture on how this help you can read My friend is not insane.

More to this topic soon.

Have fun,
Gabi