Вики Гитхаба —не для документации

Дав­но хо­тел по­де­лить­ся неболь­шим на­блю­де­ни­ем: я ча­сто вижу, что люди хра­нят до­ку­мен­та­цию в вики Гит­ха­ба. Я счи­таю, что так де­лать нель­зя. Ни в коем слу­чае. Луч­шее ме­сто для до­ку­мен­та­ции —сам ре­по­зи­то­рий про­ек­та. Ар­гу­менты:

  1. В вики нет син­хро­ни­за­ции вер­сии кода с вер­си­ей до­ку­мен­та­ции. В вики текст все­гда отоб­ра­жа­ет­ся са­мый ак­ту­аль­ный, он не за­ви­сит от того, на ка­кой ком­мит смот­рят поль­зо­ва­те­ли че­рез веб-ин­тер­фейс. По­это­му, если воз­ни­ка­ет необ­хо­ди­мость узнать ка­кой был API у кон­крет­ной вер­сии кода, при­дёт­ся вруч­ную пы­тать­ся най­ти в ис­то­рии вики мо­мент, ко­гда её со­дер­жи­мое сов­па­да­ло с нуж­ной дей­стви­тель­но­стью. Эта про­бле­ма не воз­ник­нет если до­ку­мен­та­цию хра­нить в ре­по­зи­то­рии про­ек­та: если взять нуж­ный ком­мит (нуж­ную вет­ку, нуж­ный тег), то до­ку­мен­та­ция бу­дет вид­на в том виде, в ка­ком она была на тот момент.

  2. В вики слож­нее под­дер­жи­вать до­ку­мен­та­цию в ак­ту­аль­ном со­сто­я­нии. Го­раз­до про­ще од­но­вре­мен­но с на­пи­са­ни­ем кода пи­сать и те­сты, и до­ку­мен­та­цию, чем по­том от­дель­но к ним воз­вра­щать­ся и где-то в от­дель­ном ме­сте их пра­вить. Если с са­мо­го на­ча­ла про­ек­та под­дер­жи­вать в по­ряд­ке те­сты с до­ку­мен­та­ци­ей, то и про­блем в даль­ней­шей ра­бо­те с ними не воз­ник­нет, но если за­бро­сить это дело (что очень про­сто сде­лать, ко­гда код от­де­лён от осталь­ных сущ­но­стей), то всту­па­ет в дей­ствие эн­тро­пия. И умень­ше­ние ко­ли­че­ства дей­ствий, нуж­ных для об­нов­ле­ния до­ку­мен­та­ции, де­ла­ет про­ще её под­держ­ку. Ко­гда не ну­жен лиш­ний шаг —его не нуж­но де­лать и слож­нее осту­питься.

  3. Из­ме­не­ния в ос­нов­ном ре­по­зи­то­рии про­ще от­сле­жи­вать, чем сле­дить за вики. Если от­крыть вики на всех, мож­но слу­чай­но не от­сле­дить до­бав­ле­ние кем-ни­будь оши­боч­ной ин­фор­ма­ции; то­гда как стан­дарт­ный путь вне­се­ния из­ме­не­ний че­рез пулл-рек­ве­сты —удоб­ный и на­дёж­ный. И, на­о­бо­рот, на ком­ми­ты про­ще под­пи­сать­ся, чем от­сле­жи­вать про­ис­хо­дя­щее в вики.

В ито­ге, я не вижу при­чин ис­поль­зо­вать вики для до­ку­мен­та­ции. Если кто-то смо­жет при­ве­сти ар­гу­мен­ты в поль­зу по­доб­но­го по­ло­же­ния дел —буду им рад. И если по­явит­ся смысл ис­поль­зо­вать вики, я бы хо­тел пред­ло­жить по­про­бо­вать сде­лать это не со­всем обыч­ным об­ра­зом. Вики в Гит­ха­бе, в прин­ци­пе, тоже от­дель­ный ре­по­зи­то­рий, а это зна­чит, что его мож­но под­цеп­лять са­б­мо­ду­лем к дру­го­му ре­по­зи­то­рию. Со­от­вет­ствен­но, мож­но по­про­бо­вать сде­лать вики са­б­мо­ду­лем к ос­нов­но­му ре­по­зи­то­рию с ко­дом —в этом слу­чае мы ре­ша­ем по­чти все про­бле­мы, но по­лу­ча­ем в на­груз­ку необ­хо­ди­мость сле­дить за са­б­мо­ду­лем. Но, воз­мож­но, оно того бу­дет стоить.