[c-nsp] OT: Network documentation tool

[Pavel Skovajsa]

Hi,

I believe the way the networks you manage is documented is one of the
main factors of the quality of everyday delivery. The reason for that
is that the network is "supported/operated" by different people that
actually built it, at least on the "early" levels of support.

The corrolary is, that as network-builder you need to perform a
knowledge tranfer to the support organization, therefore you need to
provide some kind of meaningful documentation. After that all you need
to do, is to find an efficient way for the support organization to
orientate in the vasts amount of documented information, to be able to
find the necessary info in timely fashion.

Having said this, it is obvious that no documenting system that allows
free unstructured placement of information is the correct answer.
Therefore I believe that no "free unstructured" documenting system
like Sharepoint, Wiki or CIFS is ideal for this job.

The need is for "strict&structured" documenting system that holds that
information about the entities on your network and their relationship.
The nature of network information that we want to document is indeed
structured therefore easily modeled by traditional decomposition
techniques. To give you an example:

1. basic entity is a device that has number of attributes - name, IP,
serial number, location etc.
2. devices have number of interfaces, each with attributes like name,
technology, speed etc. Interfaces link devices together and can be
monitored or not via our monitoring system.
3. devices belong to sites, which have subnets, visual maps, real post
addresses and people contacts
4. sites are connected by WAN links (on device interfaces) into
regions that have management contacts etc.

etc. etc.

This information can be then used more that for documentation
purposes, for example, billing, reporting etc. etc. whatever you think
about - for example devices can be linked with CVSView output from
RANCID.

No I do not know any open-source system that would have all of this,
that is why most big companies usually find some budget in order to
get something like above written from scratch.


-Pavel



On Sat, Jul 18, 2009 at 6:18 PM, <A.L.M.Buxey at lboro.ac.uk> wrote:
> Hi,
>
>> I'm looking for the perfect documentation tool for network
>
> the obvious answer is the one that works for you and
> your organisation. you say you've got a CIFS share right
> now - but, used correctly, that might be the best way.
> certainly easy to backup ;-)
>
> we used some basic WIKI - qwikiwiki and then moved onto Drupal
> which is currently in place. whilst good at providing content
> it still suffers the curse of any written stuff (elec or print)
> and that is that the network can quite easily make the docs look
> outdated - I would be very careful about what gets documented
> and detailed - something like configs are (or should be!) already
> being stored in usually a much better way - eg RANCID or another
> RCS/SVN repository.  when things go wrong you dont want
> to be digging through docs and a changelog system to try to map what
> is and what was - you want to query your configs for anything
> changed in the last eg 3 hours - thats what a proper config
> store can tell you.  the docs should be higher level like
> how the system is architectured...why you have what options
> on VLANs and links etc.  thats my $0.01
>
> (we also try to self-document as much as we can in places -
> eg config files for DHCP and DNS can be veyr verbose...likewise
> ACLs on routers/switches - use those remark commands! :-)
>
> alan
> _______________________________________________
> cisco-nsp mailing list  cisco-nsp at puck.nether.net
> https://puck.nether.net/mailman/listinfo/cisco-nsp
> archive at http://puck.nether.net/pipermail/cisco-nsp/
>