Piloting Markdown-based documentation : Using Markdown for SoC documentation
Mäkiranta, Eero (2023)
Mäkiranta, Eero
2023
Sähkötekniikan DI-ohjelma - Master's Programme in Electrical Engineering
Informaatioteknologian ja viestinnän tiedekunta - Faculty of Information Technology and Communication Sciences
This publication is copyrighted. You may download, display and print it for Your own personal use. Commercial use is prohibited.
Hyväksymispäivämäärä
2023-03-13
Julkaisun pysyvä osoite on
https://urn.fi/URN:NBN:fi:tuni-202303012687
https://urn.fi/URN:NBN:fi:tuni-202303012687
Tiivistelmä
Creating clear and easy to reach documentation for System-On-Chip (SoC) products is a cru- cial part of the SoC production. All parts of the SoC and its design flow needs to be documented in a way that the information is available for years to come. The documents needs to be also available and up-to-date during the design process.
The main problems this thesis tries to solve is the scattered documentation all over intranet pages, miss-matches between the documentation and the code base, a poor access management of these sites and the need of heavy software. Part of this thesis also addresses the problem of deploying a new tools and methodologies in a big and complex organization. The change resistance, schedule pressures and supporting the usage of a new tool are the main problems the study will look into.
A Markdown based documentation portal was created to tackle the documentation issues. Markdown is a human readable markup language which provides readability even without any third party software. A documentation portal will create a documentation sites based on the Markdown files created in the version control system. The portal provides a view on all the documents relating to a specific project.
A deployment study was conducted to find a optimal way of pushing a new tools into an or- ganization. The study consisted of literature reviews and interviewing persons with experience on deploying tools to a large masses. This study was used to plan and conduct a pilot for the documentation portal and Markdown as a way of documenting SoCs.
The tool proved to be usable at least in a small SoCs projects but due to time constraints, a wider deployment was left out of the scope. The deployment study revealed undocumented practises and improvement actions. The study will help to create a deployment template for orga- nization to use for other tools also. Järjestelmäpiirien, myöhemmin SoC, dokumentointi on kriittinen osa SoC kehitystä. Jokainen osa ja työvaihe SoCsta täytyy dokumentoida niin, että materiaali on tallessa vielä vuosienkin jäl- keen. Myös SoC kehityksen aikana dokumentaation täytyy olla saavutettavissa ja ajan tasalla.
Ongelmat, joihin tämä työ vastaa, ovat keskitetyn dokumentaatiosäiliön puute, eroavaisuudet koodin ja dokumentoinnin versioinnissa, huono käyttöoikeushallinta sekä tarve raskaille ohjelmis- toille. Osa tästä työstä myös tutkii uusien työkalujen käyttöönoton hankaluutta suuressa organi- saatiossa. Muutosvastarinta, aikataulupaineet ja käyttöönoton tukeminen ovat pääongelmat, joihin tässä työssä keskitytään.
Markdown -pohjainen dokumentaatioportaali kehitettiin vastaamaan nykyisiin ongelmiin SoC dokumentaatiossa. Markdown on ihmisluettava markup -kieli, jota on mahdollista lukea ilman kol- mannen osapuolen ohjelmistoja. Dokumentaatioportaali koostaa versionhallintaan lisätyistä Mark- down -tiedostoista dokumentaatiosivuston. Portaali tarjoaa projektinäkymän, josta loppukäyttäjä voi selailla kaikkea projektiin liittyvää dokumentaatiota.
Työkalujen käyttöönottoon liittyvässä tutkimuksessa etsittiin parhaita käytäntöjä ajaa uusia työ- kaluja organisaation käyttöön. Tutkimus koostui kirjallisuuskatsauksesta ja haastatteluista. Haas- tattelut käytiin ihmisten kanssa, joilla on laaja kokemus työkalujen käyttöönoton toteuttamisesta suurelle organisaatiolle. Tutkimuksen tuloksia käytettiin hyväksi dokumentaatioportaalin pilotoin- nin suunnittelussa ja toteutuksessa.
Dokumentaatioportaali osoittautui toimivaksi pienissä SoC -projekteissa. Ajallisten haasteiden vuoksi laajempi käyttöönotto rajattiin työn aihealueen ulkopuolelle. Käyttöönottoon liittyvä tutki- mus paljasti dokumentoimattomia käytänteitä ja loi kehitysideoita. Tutkimusta voi käyttää pohjana muidenkin työkalujen käyttöönoton suunnittelussa ja toteutuksessa.
The main problems this thesis tries to solve is the scattered documentation all over intranet pages, miss-matches between the documentation and the code base, a poor access management of these sites and the need of heavy software. Part of this thesis also addresses the problem of deploying a new tools and methodologies in a big and complex organization. The change resistance, schedule pressures and supporting the usage of a new tool are the main problems the study will look into.
A Markdown based documentation portal was created to tackle the documentation issues. Markdown is a human readable markup language which provides readability even without any third party software. A documentation portal will create a documentation sites based on the Markdown files created in the version control system. The portal provides a view on all the documents relating to a specific project.
A deployment study was conducted to find a optimal way of pushing a new tools into an or- ganization. The study consisted of literature reviews and interviewing persons with experience on deploying tools to a large masses. This study was used to plan and conduct a pilot for the documentation portal and Markdown as a way of documenting SoCs.
The tool proved to be usable at least in a small SoCs projects but due to time constraints, a wider deployment was left out of the scope. The deployment study revealed undocumented practises and improvement actions. The study will help to create a deployment template for orga- nization to use for other tools also.
Ongelmat, joihin tämä työ vastaa, ovat keskitetyn dokumentaatiosäiliön puute, eroavaisuudet koodin ja dokumentoinnin versioinnissa, huono käyttöoikeushallinta sekä tarve raskaille ohjelmis- toille. Osa tästä työstä myös tutkii uusien työkalujen käyttöönoton hankaluutta suuressa organi- saatiossa. Muutosvastarinta, aikataulupaineet ja käyttöönoton tukeminen ovat pääongelmat, joihin tässä työssä keskitytään.
Markdown -pohjainen dokumentaatioportaali kehitettiin vastaamaan nykyisiin ongelmiin SoC dokumentaatiossa. Markdown on ihmisluettava markup -kieli, jota on mahdollista lukea ilman kol- mannen osapuolen ohjelmistoja. Dokumentaatioportaali koostaa versionhallintaan lisätyistä Mark- down -tiedostoista dokumentaatiosivuston. Portaali tarjoaa projektinäkymän, josta loppukäyttäjä voi selailla kaikkea projektiin liittyvää dokumentaatiota.
Työkalujen käyttöönottoon liittyvässä tutkimuksessa etsittiin parhaita käytäntöjä ajaa uusia työ- kaluja organisaation käyttöön. Tutkimus koostui kirjallisuuskatsauksesta ja haastatteluista. Haas- tattelut käytiin ihmisten kanssa, joilla on laaja kokemus työkalujen käyttöönoton toteuttamisesta suurelle organisaatiolle. Tutkimuksen tuloksia käytettiin hyväksi dokumentaatioportaalin pilotoin- nin suunnittelussa ja toteutuksessa.
Dokumentaatioportaali osoittautui toimivaksi pienissä SoC -projekteissa. Ajallisten haasteiden vuoksi laajempi käyttöönotto rajattiin työn aihealueen ulkopuolelle. Käyttöönottoon liittyvä tutki- mus paljasti dokumentoimattomia käytänteitä ja loi kehitysideoita. Tutkimusta voi käyttää pohjana muidenkin työkalujen käyttöönoton suunnittelussa ja toteutuksessa.