Once again about the documentation
Level: Beginner, Continuing, Lazy
About the documentation has already been said a lot, including in Habré, where I found several articles. However, those articles that I watched ( one , two , three , four ) answer the questions why and what needs to be documented. I want to give two simple examples showing how, as well as demonstrating that the documentation can besoft and silky light and pleasant.
')
I believe that there is only one normal way to keep records. Ask yourself what? I think you guessed it was a wiki. Why? I’m not even going to mention the possibilities of collaboration, it’s obvious. The main advantages of the wiki system I see in the following:
1. The history of edits is saved. You can always see who is to blameand to whom in the head of his boots .
2. Easy installation, configuration and use. Wikis can be used anywhere.
I conduct documentation mainly text. But now I deviate from the topic and tell you about the scheme.
I love beautiful schemes, but I use them only as a last resort, because they have several fundamental flaws.
1. You need to download the scheme from the wiki, change it and upload it back. This disadvantage is just as important that I will focus on it especially. So, the key condition for timely documentation is the principles of “document as you go” and “document easily.” To change the documentation you need to perform the minimum number of actions. And the truth is that if in order to document a change in the network topology or in the cluster operation scheme, you need to open the scheme, modify it and upload it back, there is a rather high probability that they will not do it. And even if they are, it is not at all happy, because it is very dreary.
2. Schemes can not be searched. And even if you search by schemes in the program for creating schemes, it is unlikely that it will work when the scheme, most likely converted into a picture, is inserted into the wiki.
3. The scheme does not replace the grammatical verbal description. Of course, there are things for which the schemes are more suitable, but in my everyday practice I have come across the fact that most of the things with which I work are perfectly described by text, and sometimes the schemes are molded just for beauty.
I love the text. I will say even more, I love plaintext. It is quickly recruited and quite expressive, if properly used indents, and allows you to focus on the structure and not on the design. Structure is the most important thing. Therefore, once again I will say: “Use indents!” They allow you to focus on what you are describing without being distracted by the design, and at the same time present the information in a convenient, structured and easy-to-understand form. Maybe a little praise? Anyway.
So, a few principles of working with text:
1. Documentation is written in order to read it. Therefore, in developing the format of documentation, repel solely because it can help you in your work. Ask yourself “What should I know about this service? About this car? "
2. Write concisely. If you can not write something, because it already exists somewhere, then do not write, because from experience we get a jungle of text, which is then simply hammered. For example, server specifications, you can specify a link to a document on the manufacturer's website. So, there is no redundancy and unnecessary work!
3. Do not write, copy! If something can be taken directly from the config, take it straight from the config. The output of the command will also go. If you can make a script that you use to pull out information from configs and put it on a wiki (which is not hard), do it. The documentation on the servers themselves can be put in / etc / motd and then uploaded to the wiki, then it will be much easier for everyone to document the changes.
3. Structuring is our everything. Indent subordinate elements. You can use lists, but lists are good, but indents are better.
4. Standards of documentation should be, but common sense is more important. For example, if there are some implicit features in the functioning of the server, do a new subsection and write. If something is wrong with the server, bring it up and highlight it in red.
5. Monitoring is not documentation. Configuration management systems are also not documentation. It is clear that if there are 100 servers of the same type, then only one can be documented but, on the other hand, if you have 100 servers of the same type, then you already know that.
So, below is a template for describing the server. In a real wiki, it looks about the same as here. As you can see, I love indentations so much that I really use a lot of pre prepre tags.
The template itself consists of the following items:
1. Server Name
2. Services provided
3. Responsible
4. System
5. Monitoring
6. Backup
As shown, this is the main page. It is much more commonly used than the pages of individual servers. The meaning of this page is simple: in one place, in the simplest possible way, it is possible to describe a complete picture of the interaction of all machines.
The format of the documentation is simple. For each service (daemon) on the host, all hosts and services with which the described service interacts are recorded.
The above examples do not necessarily apply to you directly, they can and should be altered under the circumstances.
Well that's all. Hello!
UPDATE: As VolCh reasonably noted in the comments, and then also the powerman , it is convenient to use the version control system for documentation and work with the documentation as with code. The explanation is why there is in the comments. Then you can do as described by the powerman here, in my opinion a very good solution: habrahabr.ru/post/12903
UPDATE2: Added thoughts about repository documentation vs wiki documentation:
For wikis:
- If not only developers work with documentation, it is much easier to use wikis
- In a wiki, it is easier to bring documentation to one type, there will be no confusion and vacillation (from experience)
- Robots are easily attached to the wiki, so the advantages of the repository are not obvious
- If the wiki is large, it’s more convenient to do a global search. there are indexes
For repository:
- Developers will most likely find it easier to use the repository, a single system for everything
- Robots are attached easier than on a wiki
- If you already have documentation in html format, you will not be able to access the wiki in a minute, but you can easily put it into the repository.
In general, one should always choose according to circumstances. If there are some developers in the team and there are clear standards for everything - the repository, if not only developers or bad standards - wikis, if there are any other factors - consider them.
UPDATE3: In the comments dyadyavasya told that he has a positive experience using Google Docs. So if you are not afraid to give your data to the mercy of a beaver corporation, go ahead.
What's again? But why!?
About the documentation has already been said a lot, including in Habré, where I found several articles. However, those articles that I watched ( one , two , three , four ) answer the questions why and what needs to be documented. I want to give two simple examples showing how, as well as demonstrating that the documentation can be
')
What is the documentation?
I believe that there is only one normal way to keep records. Ask yourself what? I think you guessed it was a wiki. Why? I’m not even going to mention the possibilities of collaboration, it’s obvious. The main advantages of the wiki system I see in the following:
1. The history of edits is saved. You can always see who is to blame
2. Easy installation, configuration and use. Wikis can be used anywhere.
Server Documentation
I conduct documentation mainly text. But now I deviate from the topic and tell you about the scheme.
Otsuplenie about graphic schemes
I love beautiful schemes, but I use them only as a last resort, because they have several fundamental flaws.
1. You need to download the scheme from the wiki, change it and upload it back. This disadvantage is just as important that I will focus on it especially. So, the key condition for timely documentation is the principles of “document as you go” and “document easily.” To change the documentation you need to perform the minimum number of actions. And the truth is that if in order to document a change in the network topology or in the cluster operation scheme, you need to open the scheme, modify it and upload it back, there is a rather high probability that they will not do it. And even if they are, it is not at all happy, because it is very dreary.
2. Schemes can not be searched. And even if you search by schemes in the program for creating schemes, it is unlikely that it will work when the scheme, most likely converted into a picture, is inserted into the wiki.
3. The scheme does not replace the grammatical verbal description. Of course, there are things for which the schemes are more suitable, but in my everyday practice I have come across the fact that most of the things with which I work are perfectly described by text, and sometimes the schemes are molded just for beauty.
So the text
I love the text. I will say even more, I love plaintext. It is quickly recruited and quite expressive, if properly used indents, and allows you to focus on the structure and not on the design. Structure is the most important thing. Therefore, once again I will say: “Use indents!” They allow you to focus on what you are describing without being distracted by the design, and at the same time present the information in a convenient, structured and easy-to-understand form. Maybe a little praise? Anyway.
So, a few principles of working with text:
1. Documentation is written in order to read it. Therefore, in developing the format of documentation, repel solely because it can help you in your work. Ask yourself “What should I know about this service? About this car? "
2. Write concisely. If you can not write something, because it already exists somewhere, then do not write, because from experience we get a jungle of text, which is then simply hammered. For example, server specifications, you can specify a link to a document on the manufacturer's website. So, there is no redundancy and unnecessary work!
3. Do not write, copy! If something can be taken directly from the config, take it straight from the config. The output of the command will also go. If you can make a script that you use to pull out information from configs and put it on a wiki (which is not hard), do it. The documentation on the servers themselves can be put in / etc / motd and then uploaded to the wiki, then it will be much easier for everyone to document the changes.
3. Structuring is our everything. Indent subordinate elements. You can use lists, but lists are good, but indents are better.
4. Standards of documentation should be, but common sense is more important. For example, if there are some implicit features in the functioning of the server, do a new subsection and write. If something is wrong with the server, bring it up and highlight it in red.
5. Monitoring is not documentation. Configuration management systems are also not documentation. It is clear that if there are 100 servers of the same type, then only one can be documented but, on the other hand, if you have 100 servers of the same type, then you already know that.
Template for server description
So, below is a template for describing the server. In a real wiki, it looks about the same as here. As you can see, I love indentations so much that I really use a lot of pre pre
The template itself consists of the following items:
1. Server Name
2. Services provided
3. Responsible
4. System
5. Monitoring
6. Backup
Server name
powerconsumer.site Services provided
--------------------------- : , 10^100 . , memeater. : Memory eating service, socket http://bofh.ntk.net/BOFH/ 80/tcp : /usr/local/bin/cpueater init-: /etc/init.d/cpueater : /srv/bofh/cpueater : /var/log/cpueater[1,7] : every day, keeping last 7 days : http://zabbix.site/cpueater/ : /etc/cpueater/cpueater.conf ----------------------- : , . : Memory eating service, socket http://bofh.ntk.net/BOFH/ 80/tcp : /usr/local/bin/memeater init-: /etc/init.d/memeater : /srv/bofh/memeater : /var/log/memeater[1,7] : every day, keeping last 7 days : http://zabbix.site/memeater/ : /etc/memeater/memeater.conf Responsible
BOFH System
Debian Squeeze 6.04 Disk subsystem -------------- RAID-6 on LSI-based controller with 10 active disks and 2 hot-spares. 10.0GB ext4 / boot 10.0GB linux-swap(v1) swap 10.0GB ext4 /tmp 10.0GB ext4 /usr 20.0GB ext4 /var 40.0GB ext4 /home 20.0GB /opt 2300GB /srv/bofh Network subsystem ----------------- iface eth0 inet static address 192.168.1.10 netmask 255.255.255.0 network 129.168.1.0 gateway 192.168.1.1 up sleep 5; /sbin/ethtool -s eth0 autoneg off speed 100 duplex full Monitoring
Zabbix-agent with custom scripts: /opt/zabbix/cpueater.py /opt/zabbix/memeater.py Backup
/srv/bofh/cpueater/ /srv/bofh/memeater/ The interaction between the servers
As shown, this is the main page. It is much more commonly used than the pages of individual servers. The meaning of this page is simple: in one place, in the simplest possible way, it is possible to describe a complete picture of the interaction of all machines.
So, if you are too lazy to keep records, at least do it!
The format of the documentation is simple. For each service (daemon) on the host, all hosts and services with which the described service interacts are recorded.
balancer.site ------------- ngnix: --> webserver0.site/ngnix: 80/tcp ngnix: --> webserver1.site/ngnix: 80/tcp webserver0.site --------------- php-fpm: --> sql.site/postgresql: 5423/tcp webserver1.site --------------- php-fpm: --> sql.site/postgresql: 5423/tcp sql.site -------- postgresql: --> backup.sql.site/postgresql: 22/tcp backup.sql.site --------------- amanda.site ----------- amanda-server: --> balancer.site/amanda-client: 30000-30100/tcp, 10800/udp amanda-server: --> webserver0.site/amanda-client: 30000-30100/tcp, 10800/udp amanda-server: --> sql.site/amanda-client: 30000-30100/tcp, 10800/udp zabbix.site ----------- zabbix-server: --> balancer.site/zabbix-agent: 10050/tcp zabbix-server: --> webserver0.site/zabbix-agent: 10050/tcp zabbix-server: --> webserver1.site/zabbix-agent: 10050/tcp zabbix-server: --> sql.site/zabbix-agent: 10050/tcp zabbix-server: --> backup.sql.site/zabbix-agent: 10050/tcp zabbix-server: --> amanda.site/zabbix-agent: 10050/tcp At last
The above examples do not necessarily apply to you directly, they can and should be altered under the circumstances.
Well that's all. Hello!
UPDATE: As VolCh reasonably noted in the comments, and then also the powerman , it is convenient to use the version control system for documentation and work with the documentation as with code. The explanation is why there is in the comments. Then you can do as described by the powerman here, in my opinion a very good solution: habrahabr.ru/post/12903
UPDATE2: Added thoughts about repository documentation vs wiki documentation:
For wikis:
- If not only developers work with documentation, it is much easier to use wikis
- In a wiki, it is easier to bring documentation to one type, there will be no confusion and vacillation (from experience)
- Robots are easily attached to the wiki, so the advantages of the repository are not obvious
- If the wiki is large, it’s more convenient to do a global search. there are indexes
For repository:
- Developers will most likely find it easier to use the repository, a single system for everything
- Robots are attached easier than on a wiki
- If you already have documentation in html format, you will not be able to access the wiki in a minute, but you can easily put it into the repository.
In general, one should always choose according to circumstances. If there are some developers in the team and there are clear standards for everything - the repository, if not only developers or bad standards - wikis, if there are any other factors - consider them.
UPDATE3: In the comments dyadyavasya told that he has a positive experience using Google Docs. So if you are not afraid to give your data to the mercy of a beaver corporation, go ahead.
Source: https://habr.com/ru/post/143920/
All Articles