Community archive

Ask something
Discussion Locked

How to go about developing a documentation methodology?

0 helpful
16 replies

by shdowflare 1 view

Closed to new repliesThis discussion is closed. It stays readable, but it takes no new replies.

Hey all,

I'm rather new to posting on the forums here but I do love the outstanding and diverse information I find on this site.

Finally I've come to a topic that I can't seem to find much information about. It seems my new manager is assigning me a 2009 goal of developing a documentation methodology for our IT infrastructure architecture, standards, procedures, processes, etc. It seems we need a standardized manner of not only what type and quality of documents we produce, but exactly how we produce them, where they live, and how they are maintained as well.

Anyone have any clues on where I can start on such a journey?

Thanks in advance, and I very much welcome the advice!

16 replies

by tony hopkinson

Corrective Actions
If whatever you have in place fails for some reason. Document the failure, come up with a potential solution and track it for effectiveness.

Ownership
The people who use the documentation, should be responsible for maintaining it.
Coding standards = coders.
Config = admins

If you take those into account, it suggests you get something in place, and let it evolve.

Somethings you can do right at the start, like a centralised store Sharepoint or a wiki, maybe.

Some starter for ten templates, revision history. Authoriation review, 'Beta' documents.

Don't go mad on dotting all the i's and crossing all the ts in a pedantic fashion.

What I can guarantee, is if the people maintaining the documentation, don't get anything out of them, they'll be as good as your enforcement policy, which is of course what 'you' want out of them.

Don't double document.
Classic in coding, is you will comment everything and you get.

int numberofinvoices; // the number of invoices

by jaqui

are needed, as we both know.

it's defining the method is where the issues rise. the micro manager would say document / comment everything, leading to the type of thing in your example.

My own preference is to define the purpose of a function in a comment block just before the function.

The other things for coding, the layout of the code for readability, tabs vs spaces, indentation, newlines ...
[ I say spaces, tab stops can be altered to change size of indentation and screwing layout of code to easily ]

and code practices, like do not use overloading of operators.
[ which helps with readability, and more importantly, avoids errors from processing order that can happen with overloading. ]

by tony hopkinson

how you use it is up to you.

int myFunction(int f)
/// The is function returns the square of f

is an obvious nonsense in terms of explaining the code.

int SquareOf(int f)
/// The is function returns the square of f

isn't if you are using some sort of (java)doc mechanism, but while you are using comment to do it, it isn't a comment as such.

Readable code, coding standards, standard designs, jargon busters, data dictionaries, all a lot better than over commenting.

Documenting code and commenting code, two very different animals.

If everybody is comfortable with do 'comments' in code, they get something out of it, and because of those are happy to maintain them along with the code, fair enough. In my experince though, this is not exactly the case. :p

That line between useful and burdensone is easy to cross and get over to useless.

You see a piece of code where the comment is obviously rubbish, from then on all comments will be ignored or at least be treated with extreme suspicion.

We shouldn't have started this, we'll get the comment how it does in pseudo code first mob in now.... :(

I avoid operator overloading like the plague, to me that's more about tersenes than readability.

Sum(BCD a, BCD b);

a + b;

Don't see the point.

Just being clever for it's own sake, which is never a good idea.

by jaqui

documenting hardware for the network?
documenting business practices?
documenting code?

a definition of what your boss was thinking about will help get better answers.

by shdowflare

Not so much code, but rather infrastructure/systems based documentation.

Here are some examples given to me by peers. They provide an idea of what we need, but I'm trying to see if there's a guiding force - a pre-existing methodology or framework - which I can use to get going on this:

? Infrastructure Assessment Document
? Functional and Technical Specs
? Technical Design Spec
? Technical Review Board Checklist
? System Outage and Recovery plan
? Go Live Checklist
? Go Live support Matix
? SOP Template
? Checklists (Security, operations, database)
? SLA agreements
? Redbook / Recovery plans
? Use cases
? Requirements
? Test plans
? Dates and times (Schedule)
? Application system requirements / sizing info
? Expected growth
? Business customer contact information
? List of critical applications and integrations
? Workflow
? Monitoring systems and URLs (Openview, Checkpoint, NetCool, vCenter, NetMRI, etc)
? Monitored objects list (databases, OSs, backup, bandwidth, etc)
? Network diagrams (WAN, LAN, route, Portal)
? Datacenter plans
? Network asset list
? Storage map
? DR plan
? Security policies
? POC directory (who is responsible for what system or component)

As you can see, lots of stuff here. There are the types of documents I'm talking about. I need to implement a model for producing this documentation in a consistent, reliable, maintainable manner. Any idea how/where to start with an effort like this?

by jessie

It sounds to me like some of the principles of ITIL would help you out here. Start small, depending on the size of your organization, a simple Excel spreadsheet (or OpenOffice spreadsheet) as a repository for WHAT information you're wanting to track and where the details and revision histories of documentation can be found. Basically, build your documentation like you'd build an OU structure, so that documents are easy to find because they'll be in a standardized location, i.e. \documentation\package\revision

by tony hopkinson

You end up doing so much work to to make it work, in the end it's not quicker.

If you want quick, just set up a wordpress wiki (WAMP or LAMP). It will take about a day,and it has the functionality you need, to maintain, lay out document, contribute and cross reference.

Ends up being as big and as complex as you need. Spreadsheet is an MBA solution, only suited for trivial needs. It's an enterprise solution using Access.

by jaqui

but I was thinking more like:
//Format query result set for display
int display(char $result[], int $size)
{
code
}

where the function is a fairly lengthy bit of code with calls to other functions, making it less obvious than your example.

by tony hopkinson

But I'd naturally have two functions there
one to do the formatting, which could quite possibly call a few others. And one for the display.
With the bulk of my work done in Delphi and C# and it's compilers inlining if the optimiser things it's worth while, I'm in the one page per function and always one function per function.

There's no particular right or wrong at the level we are discussing, and writing readable code is dependant on your environment. If inlining is manual, and my route is chosen, it's at the cost of performance which needs thinking about.

This is why any documentation methodology should have some way of evolving to meet need. Set some external standard in stone, and you end up with unmaintainable documentation and code.

Document readable code, as opposed to making code readable by documenting it, is what I aim for. There are of course a shed load of compromises involved in that.
Including agreeing what constitutes readable. :p

by jaqui

we have both had to go over code long after it was written and try to figure out what it's doing.

that's why we agree on most points for readability, and good commenting.

by tony hopkinson

even our own ! :p

Which is where ownership comes in, Some manager in an office, who may never have or certainly doesn't now, maintain a system, should never get a say in the nitty gritty detail.
It must be ITIL compliant, TickIT, ISO 9000, yes.

Increase productivity, by reducing the time taken for comprehension, with the corresponding acknowledgement, that documentation requires resource, no problem.

Providing the tools and facilitating the processes to do it, of course.

You will put the starting brace at the end of the first line of code, get the f**k out of here.

Before anyone says mandating that, is silly, I have worked at places where some fool did.

One complete pratt came up with this

bool SomeFunc()
{
bool retval = true;
While retval Do
{
If some condition
{
break;
}
}
return
}

Only allowed to have one return in a function !
That was the rule.

Some loops were just while (true) and relied on a break to exit!

Got to be up there for the dumbest idea of the decade award.

by road-dog

Archive schematics, configurations, address spreadsheets in a central location. I call mine "D.C.U.P." Drawings, Configurations, Utilities, Programs. Awkward but memorable.

Every work order needs a check box or initial to update affected documentation after the job, Including redlining existing schematics.

Make your process complete enough to give you necessary info, but not so cumbersome it gets ignored. Make sure management makes documentation process compliance a part of employee evaluations. Stress that once documentation accuracy falls below 90 or so percent, it is useless if you can't trust it.

Good luck, it's a thankless and consuming job until it saves the day.

by cg it

need for your IT infrastructure, standards, procedures and processes.

Almost all small business and some of the medium sized businesses that have small or no IT departments don't have adequate documentation. So... an IT person doesn't really know how the network is setup, how it changed over time, what was changed, when it was changed and why it was changed. That old "who, what, where, when, why and with that, the how you go about doing it.

by shdowflare

Yeah, we've grown so much over the past eight years that I've been here. We had about 3,000 employees when I started and now we've grown to 10000+ with acquisitions and mergers. We have some "controlled" documentation today that exists for our validated systems, but in general IT does not have any standard practices or requirements for producing documentation.

I specifically work on the Project/Enterprise Architecture group. Part of my job is to design and implement the infrastructure portion of IT projects. Part of my job is also to develop the standards and models which will drive the IT organization. In the past, my role was more support-based so it wasn't as critical to "hand-off" documentation as I handled daily, day-to-day troubleshooting and operational roles. Now that I'm on the architectural and project-based team, we need to ensure strong documentation is prepared before our systems go into production for support by the other tiers.

This documentation effort will tie into our IT PMO framework. So I imagine the documentation will reflect the various phases of the IT project. There are so many things to be covered, that I was just wondering if there's a proven, existing methodology that I can use to guide me here.

by cg it

Planning actually produces the documentation needed. Change control documents changes from the plan. Policies and procedures document who changes what, [the policy] and how that change happens [the procedure to make the change].

This is basically all inclusive to all departments. For instance, an employee quits. There is an exit procedure for Human Resources and this procedure also includes IT stuff. Another example is a new hire. HR has a procedure for this including generating the paper for creation of a user account and email box plus what rights and permissions they will have for the job they do. There's your documentation.

If your network needs upgrading, one creates a plan. That plan [final plan] becomes the infrastructure documentation.

Just some examples.

This discussion is closed to new replies.