Simplify documentation - Githubissues

dsmrreader / dsmr-reader

DSMR-telegram reader & data visualizer for hobbyists. Free for non-commercial use.

https://dsmr-reader.readthedocs.io

Other

464 stars 95 forks source link

Simplify documentation #1686

Open dennissiemensma opened 2 years ago

dennissiemensma commented 2 years ago

Feature

Overwegen om alle documentatie naar Github te verplaatsen, zodat alles op 1 plek staat.

Voordeel is ook dat er hier issues en discussies (en ook polls) gedaan kunnen worden.
Verder geen vertalingen meer ondersteund, wat de drempel om docs bij te werken (of uit te breiden) aanzienlijk verlaagt.

Ik heb al kort gekeken wat de gevolgen zijn. Het grootste nadeel is:

Geen vertalingen meer, maar opzich is Engels als voertaal voor documentatie prima
Mogelijk geen meerdere versies meer. Niet perse een probleem, maar soms wat het handig om v4-installaties te verwijzen naar een v4-variant van een stukje documentatie.
Geen zoekmachine index, al kan ik op readthedocs natuurlijk wel verwijzen.
Staat los van de code, dus handmatig in sync

Wellicht beginnen met een opzet van een deel van de Engelse docs. Kan gewoon naast bestaande docs en ook net zo makkelijk weer geannuleerd worden als het toch niet zo werkbaar blijkt.

dennissiemensma commented 2 years ago

Oh blijkbaar ondersteunt het ook restructured format, wat ik nu gebruik voor readthedocs, maar eigenlijk wil ik daar vanaf. Vind het een vreselijk format.

dennissiemensma commented 2 years ago

Blijkbaar zit er een aparte repo achter: https://github.com/dsmrreader/dsmr-reader.wiki.git

dennissiemensma commented 1 year ago

Ik laat deze zo. Zolang RTD de hosting blijft doen, kan ik ermee leven dat het los staat van Github.

dennissiemensma commented 5 months ago

Ik ga dit toch doen, maar in versimpelde vorm, zonder vetalingen. DSMR-reader app zelf blijft NL/EN, want die wijzigt amper.

De docs doe ik alleen Engels en ook alleen op Guithub, gewoon in Markdown of iets. Binnen het project.

dennissiemensma commented 5 months ago

Het formaat van de sphinx docs is namelijk echt bananen en het vertalen kost me echt teveel tijd.

dennissiemensma commented 5 months ago

Ik verplaats alles naar MD files in een nieuwe root dir. Ook tegen verwarring.

dennissiemensma commented 5 months ago

Het enige nadeel is dat ik er niet maar "1 versie" van kan hebben, door de natuur van Git. Dus ik check die Wiki alsnog wel even, of dat het fixt

dennissiemensma commented 5 months ago

Het is ook alweer bijna twee jaar geleden sinds mn vorige poging, dus wellicht is het weer wat uitgebreid: https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis

dennissiemensma commented 5 months ago

Geen nieuwe features, maar het is wel stukken duidelijker, dus ik geef het een kans

dennissiemensma commented 5 months ago

Ah ik weet het alweer. Geen ondersteuning voor subpagina's. Opzich nog steeds geen ramp, want dat betekent dat ik de docs binnen de repo moet houden, daar kan het wel.

En ik kan dan de wiki gebruiken als placeholder om te wijzen naar de oude en nieuwe docs.

dennissiemensma commented 5 months ago

Oke docs binnen de repo mist autodetectie enzo. Wellicht dan toch maar bij Read the Docs blijven, maar kijken of markdown daar kan:

https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html

En dan de NL-vertalingen droppen.

dennissiemensma commented 4 months ago

Opzet via markdown werkt prima:

https://dsmr-reader.readthedocs.io/en/work-in-progress-v6/

Het mist wat mooie dingen, zoals die tips en warnings, maar de eenvoud wint het daarin.

Plus dat ik ook dingen ga weghalen die oud zijn.

dennissiemensma commented 4 months ago

Nu ook betere template gevonden: https://dsmr-reader.readthedocs.io/en/work-in-progress-v6/ Deze pakt de hele breedte, wat een verademing is. Ik heb het niet zo op het standaard RTD-theme, wat het halve scherm niet gebruikt