Yksi dokumentaatio, kaksi tapaa ottaa järjestelmä haltuun

One documentation, two ways to take over a system

Perusta on sama: koodista johdettu dokumentaatio, jonka jokainen väite on sidottu lähdetiedostoihin, committiin ja tarkistuksen tilaan. Sen päälle järjestelmä otetaan haltuun kahdella tasolla — ymmärryksen ja ylläpidon. Kumpaakin voi käyttää yksin.

The foundation is the same: documentation derived from the code, where every claim is tied to source files, a commit and a review state. On top of it, the system is taken over on two levels — understanding and maintenance. Either can be used on its own.

Ensimmäinen päätös ei ole iso projekti.

The first decision is not a large project.

Muutoksen aloittamisen pitää olla halpaa ja konkreettista. Ensin katsotaan yhdessä, mitä järjestelmästä löytyy, ja pilotissa näette tuloksen omasta koodistanne ennen isompaa päätöstä.

Starting the change should be low-cost and concrete. First we look together at what the system contains, and in the pilot you see the result on your own code before a larger decision.

Tavoite on madaltaa ensimmäisen askeleen riskiä: 750 eurolla saatte ohjatun alustavan tilannekuvan. Pilotin rajaus ja kanava vahvistetaan erikseen ihmisen kanssa ennen toteutusta.

The goal is to lower the risk of the first step: for €750 you get a guided initial current-state picture. The pilot scope and channel are confirmed separately with a person before implementation.

Näin näette, mitä olette ostamassa

See what you are buying

Pilotin arvo ei ole raportin ulkonäössä vaan siinä, että jokainen väite voidaan jäljittää lähdetiedostoihin, committiin ja tarkistuksen tilaan. Kun väitteen varaan tehdään päätös, arkkitehti käy sen läpi asiakkaan kanssa. Siksi näytämme avoimesti, miltä valmis tuotos näyttää.

The value of the pilot is not the look of the report, but the fact that every claim can be traced to source files, a commit and a review state. When a decision depends on a claim, an architect reviews it with the customer. That is why we show what the finished output looks like.

Mistä tiedät ettei dokumentaatio ole uskottavan näköistä puppua? Jokainen dokumentti kantaa mukanaan sen, mistä se on johdettu: lähdetiedostot, git-viite ja tarkistuksen tila. Tämä on aito lohko näytteestä:

How do you know the documentation is not plausible-looking nonsense? Every document carries what it was derived from: source files, a git reference and its review state. This is a real block from the sample:

Kanava 2 käytännössä · AI tekee, ihminen päättää

Edellinen näyte on omasta koodistamme, jonka tunnemme — se on meille helppo tapaus. Siksi teimme saman työn koodipohjaan jota emme ole kirjoittaneet: dokumentoimme sen ja veimme läpi yhden oikean tiketin. Komennot ovat työn halpa osa. Rajaus, osa-aluejako ja sen ratkaiseminen mikä väite kestää, ovat arkkitehdin päätöksiä.

Koodipohja on Linked Events — MIT-lisensoitu julkinen tapahtuma-API, jota emme ole kirjoittaneet emmekä tunteneet etukäteen. Projekti valittiin itse eikä siitä ole sovittu kenenkään kanssa: kyseessä ei ole toimeksianto eikä asiakassuhde, eikä työn ollut tarkoituskaan tuottaa projektille mitään. Muutos tehtiin paikalliseen ympäristöön, ei projektin omaan koodipohjaan.

Tiketti: lisää sovelluksen admin-sivulle nappi, joka näyttää käynnissä olevan version tiedot.

Ennen

Jälkeen

→ Katso koko läpivienti videolla — 7 min, suomeksi: kartoitus, dokumentointi, tiketin valmistelu ja toteutus alusta loppuun.

Kun pilotti on tehty

After the pilot

Suunta valitaan pilotin jälkeen. Samalla määritellään ensimmäistä kertaa tarkemmin kuka tekee työn, missä ympäristössä, millä repo-oikeuksilla ja kenen AI-työkaluilla.

The direction is chosen after the pilot. This is also where we first define who does the work, in which environment, with which repository access and with whose AI tools.

Kanava 1 · dokumentaation ylläpito ja jakelu

Channel 1 · documentation maintenance and distribution

Jos kehittäjänne jatkavat omalla tavallaan, dokumentaatio vanhenee, ellei joku pidä sitä ajan tasalla. Vanhentunut vastaus AI-chatissa on vaarallisempi kuin vastaamatta jättäminen, koska se kuulostaa varmalta. Tässä mallissa vnetcon seuraa koodimuutoksia, päivittää ja tarkistaa dokumentaation ja julkaisee uuden version. Kehittäjienne repoon ei tarvitse koskea.

If your developers keep working their own way, the documentation goes stale unless someone keeps it current. A stale answer in an AI chat is more dangerous than no answer, because it sounds certain. In this model vnetcon follows code changes, updates and reviews the documentation and publishes a new version. Your developers’ repositories do not need to be touched.

Kanava 2 · ylläpidon haltuunotto

Channel 2 · taking over maintenance

Tässä dokumentaatio antaa AI:lle tiketin aloituskontekstin: mitä järjestelmän osaa muutos koskee, mihin tiedostoihin se liittyy ja mitä muuta samaan dataan osuu. Ilman tätä kontekstia AI arvaa vaikutusalueen. Jokaisesta tiketistä jää kirjattu jälki, ja dokumentaatio päivittyy samassa muutoksessa. Tyypillisesti työn tekee vnetcon, mutta sama menetelmä toimii myös teidän omalla tiimillänne.

Here the documentation gives AI the starting context for a ticket: which part of the system the change touches, which files are involved and what else uses the same data. Without that context, AI guesses the blast radius. Every ticket leaves a recorded trail, and the documentation is updated in the same change. Typically vnetcon does the work, but the same method also works with your own team.

4 500 €/kk on rajattu tikettivirta sovitussa koodialueessa. Sitä kannattaa verrata oman kehittäjän kokonaiskustannukseen tai ostetun konsulttityön kuukausimäärään, ei yksittäiseen tuntihintaan.

€4,500/mo is a scoped ticket flow in an agreed code area. Compare it with the full monthly cost of your own developer or the monthly volume of bought consulting work, not with a single hourly rate.

Menetelmä · vnetcon-docs

The method · vnetcon-docs

Yllä kuvattu dokumentointi tehdään vnetcon-docs-menetelmällä, jonka olemme kehittäneet suurissa tuotantokoodipohjissa ja julkaisseet avoimena lähdekoodina (Apache-2.0). Samassa repossa on myös MCP-palvelin, jolla dokumentaatio jaetaan. Avoimuus ei ole kutsu ottaa menettelyä käyttöön itse, vaan tapa näyttää tarkalleen, miten työmme tehdään: jokainen väite on jäljitettävissä, katvealueet sanotaan ääneen, ja menettely on tarkastettavissa eikä pelkkä lupaus.

The documentation work described above is done with the vnetcon-docs method, which we developed against large production codebases and published as open source (Apache-2.0). The same repository also contains the MCP server used to distribute the documentation. Openness is not an invitation to adopt the method yourselves, but a way to show exactly how our work is done: every claim is traceable, blind spots are stated out loud, and the method can be audited rather than just promised.

Menetelmä on yksi työväline, ei koko toimintamme. Sovellukset, agentit, spec-vetoinen kehitys ja koodianalyysi onnistuvat myös ilman sitä — tarvittaessa teidän omilla työkaluillanne, prosesseillanne ja dokumentaatiokäytännöillänne. Jos teillä on jo tapa, johon haluatte pitäytyä, sekin sopii.

The method is one instrument, not the whole of what we do. Applications, agents, spec-driven development and code analysis all work without it — and with your own tools, processes and documentation conventions where that is what you want. If you already have a way of working you intend to keep, that is fine too.

Hinnat alv 0 %. Ensimmäinen toimeksianto uudessa teknologiapinossa hinnoitellaan pilottihintaan vastineeksi referenssistä ja mittausdatasta — kysy.

Prices exclude VAT. The first engagement in a new technology stack is priced as a pilot in exchange for a reference and measurement data — just ask.