Advies: Software voor maken documentatie voor end-user

[Skyaero]

Mijn bedrijf heeft eigen saas-software ontwikkeld, waar inmiddels de nodige klanten gebruik van maken. Documentatie voor deze eind-klanten laat echter te wensen over. Documentatie is karig en nu nog onderdeel van de saas-applicatie zelf en bestaat feitelijk uit ASP.NET pagina's.

Dat willen we anders en professioneler aanpakken. Het liefst via een (eventueel betaalde) derde leverancier - we gaan niet het wiel opnieuw uitvinden.

Eisen:

1. Doelgroep voor de documentatie is de (niet-technische) gebruiker van de saas-software, denk niveau projectmanager
2. De gebruiker van de documentatie-software heeft niet per se een developer-achtergrond. Dus geen git-achtige dingen. Bij voorkeur WYSIWYG. Markdown is misschien nog wel aan te leren.
3. Online dienst, dus niets zelf hoeven te installeren.
4. Gericht op MKB, we hebben geen Enterprise budget
5. Europees bedrijf
6. Koppelen van een eigen domeinnaam
7. navigatiefuncties zoals zoekbalk zijn zeer gewenst
8. Publiek toegankelijk en privaat beheerd

Wat ik al gevonden heb?
Docusaurus -> voldoet niet aan (3)
Confluence -> voldoet niet aan (4)
Mintlify -> voldoet niet aan (5)
Document360 -> voldoet niet aan (5)
ArchBee -> voldoet niet aan (5) en zit op de rand van (4)
MkDocus -> voldoet niet aan (3)

Om een beeld te schetsen wat voor software we zoeken: voor onze sales (CRM) zijn we in zee gegaan met het Belgische Teamleader.eu.

[Groax]

Ik ben niet heel erg thuis in ASP.NET, maar misschien is DocFX iets voor jou? Het kan vanuit je applicatie gebouwd worden.

[ Voor 5% gewijzigd door Groax op 27-08-2024 16:18 ]

[ThomasG]

Groax schreef op dinsdag 27 augustus 2024 @ 16:17:
Ik ben niet heel erg thuis in ASP.NET, maar misschien is DocFX iets voor jou? Het kan vanuit je applicatie gebouwd worden.

DocFX wordt door Microsoft zelf gebruikt voor bijvoorbeeld de .NET documentatie (source code).

[SPee]

Waarom zoekt een bedrijf dat een SAAS maakt een andere SAAS dienst om hun docs te hosten ipv dat zelf te doen?

Anyway, mijn suggesties zijn:

• Sphinx (selfhosted)
• DocFX (selfhosted)
• Read the Docs (hosted)
• Github Pages (hosted)
• Een wiki site
• Een wordpress site

[RobIII]

@Groax @ThomasG @SPee DocFX voldoet lijkt me niet aan punt 1: "Doelgroep voor de documentatie is de (niet-technische) gebruiker van de saas-software, denk niveau projectmanager". De technische documentatie die je genereert met DocFX op basis van comments in je code is andere documentatie dan de documentatie die je je projectmanagers voorschotelt. Althans: alle projectmanagers die ik ooit documentatie heb voorgeschoteld

Overigens kún je wel dergelijke documentatie met DocFX maken, maar het is toch wel heel erg code-focussed als je 't mij vraagt.

quote: https://dotnet.github.io/docfx/docs/basic-concepts.html

Docfx can be used as a static site generator, but the real value of the tool is in bringing together static documentation pages and .NET API documentation.

Edit: Maar goed, bij nader inzien trek ik mijn reactie toch maar in denk ik; het is minder code-focussed dan ik dacht.

[ Voor 38% gewijzigd door RobIII op 28-08-2024 21:08 ]

[Skyaero]

SPee schreef op woensdag 28 augustus 2024 @ 20:48:
Waarom zoekt een bedrijf dat een SAAS maakt een andere SAAS dienst om hun docs te hosten ipv dat zelf te doen?

Omdat we op dit moment niet de capaciteit hebben om dat allemaal zelf te ontwikkelen. En waarom zouden we het wiel opnieuw uitvinden?

De suggestie van een wiki is overigens nog niet zo gek. Daar had ik nog niet aan gedacht.

[ Voor 12% gewijzigd door Skyaero op 28-08-2024 21:44 ]

[Anoniem: 80910]

Ikzelf heb de keuze voor documentatie in markdown gemaakt, valt makkelijk te leren en kun je goede html documenten mee maken.

Ik zou voor een apart domein / subdomein kiezen.

Punt 2 snap ik niet, jullie maken toch de documentatie en de gebruiker leest de documenten?

Een documentatie website is zo gemaakt. Je installeerd bijvoorbeeld php apache laravel, een markdown parser (zie ander topic) zet het wellicht in docker en een aparte git repository.

Wat wil je kwijt zijn aan documentatie, je commit md files naar git en bij een nieuwe versie update je de server met een git pull.

Wil je er ook pdf's van maken ?

[ThomasG]

RobIII schreef op woensdag 28 augustus 2024 @ 21:03:
@Groax @ThomasG @SPee DocFX voldoet lijkt me niet aan punt 1: "Doelgroep voor de documentatie is de (niet-technische) gebruiker van de saas-software, denk niveau projectmanager". De technische documentatie die je genereert met DocFX op basis van comments in je code is andere documentatie dan de documentatie die je je projectmanagers voorschotelt. Althans: alle projectmanagers die ik ooit documentatie heb voorgeschoteld

Overigens kún je wel dergelijke documentatie met DocFX maken, maar het is toch wel heel erg code-focussed als je 't mij vraagt.

Nee hoor. DocFX ondersteund gewoon markdown als basis voor je documentatie. Steker nog, het merendeel van de .NET documentatie is gewoon markdown; wat wordt aangevuld met documentatie uit code, maar dat is een klein deel. Het is dus prima mogelijk.

[Skyaero]

Anoniem: 80910 schreef op woensdag 28 augustus 2024 @ 22:53:
Punt 2 snap ik niet, jullie maken toch de documentatie en de gebruiker leest de documenten?

De 'gebruiker' van de documentatiesoftware is niet hetzelfde als de lezer (= gebruiker van onze SAAS software) van de documentatie.

Het gaat hier niet om API of van developer-voor developer documenatie, maar documentatie over hoe met de software te werken en de (domein)achtergrond.

Denk aan bijvoorbeeld boekhoudsoftware, waar de documentatie uitlegt hoe je een factuur inboekt, maar ook achtergrond geeft over hoe een goede factuur te maken.

De personen die binnen onze organisatie deze documentatie schrijven hebben geen developer achtergrond, maar zijn bijvoorbeeld domein-specifiek consultant of tekstschrijver. Dat zijn personen die geen git gaan leren.

Een documentatie website is zo gemaakt. Je installeerd bijvoorbeeld php apache laravel, een markdown parser (zie ander topic) zet het wellicht in docker en een aparte git repository.

Wat wil je kwijt zijn aan documentatie, je commit md files naar git en bij een nieuwe versie update je de server met een git pull.

Of ik denk te moeilijk, of je doet het veel te simpel voorkomen. Het opzetten en configureren van deze technologieën kost tijd, het borgen van onderhoud en updates nog veel meer. Hebben we het nog niet gehad over de release en test pipelines en blijft het probleem van de aanwezigheid van git voor mensen die daar nog nooit mee gewerkt hebben.

[Anoniem: 80910]

Test pipelines op markdown documenten ?

Git bied versie control, hoe wil je dat doen ?

Hoeveel mensen gaan er mee werken ?

Git en een markdown editor en viewer zit bijvoorbeeld in phpstorm, dan wordt er op knopjes gedrukt en het (inclusief git) werkt.

Updates in van 1 a 2x per jaar het gekozen php framework updaten en omdat je het bijna niet gebruikt, weinig wijzigingen, dus max. 1 dag per jaar de documentatie software bijwerken.

Het opzetten zal ook wel binnen 1 a 2 dagen te realiseren zijn.

De server moet ook up2date zijn en je hebt je budget nog niet gegeven.

Git is ook gelijk een backup systeem van je documentatie.

@Arie- zo beter? Anders moet je ff duidelijker zijn wat je niet snap aan mijn reactie?

[ Voor 11% gewijzigd door Anoniem: 80910 op 29-08-2024 16:49 ]

[Arie-]

@Anoniem: 80910 Wat bazel je allemaal, kun je iets meer structuur in je betoog aanbrengen. Ik kan er óók niets van maken.

@Skyaero Is een wiki een optie: makkelijk op te zetten en te onderhouden door niet ontwikkelaars. Ik herken je probleem wel hoor, want aan drie forumulieren een knop toevoegen betekent al snel
* drie nieuwe screenshots
* drie stukjes tekst die de functionaliteit aanduiden
* eventueel extra uitleg die de toepassing in de context toelichten
Daar wil je als ontwikkelaar niet bezig mee zijn.

Edit: arg zie dat @SPee dat ook al had genoemd.
Edit2: dat had je zelf ook al opgemerkt

[ Voor 7% gewijzigd door Arie- op 29-08-2024 12:28 ]

[Cartman!]

@Anoniem: 80910

De personen die binnen onze organisatie deze documentatie schrijven hebben geen developer achtergrond, maar zijn bijvoorbeeld domein-specifiek consultant of tekstschrijver. Dat zijn personen die geen git gaan leren.

Die personen gaan niet in een IDE werken, laat staan dat ze versiebeheer/Git gaan leren. Daarom zoekt de TS een SaaS tool

--

Zelf vind ik MediaWiki best een prima tool. Je kunt deze zelf hosten (maar moet je dan beheren) of je kunt een hosted versie nemen: https://www.mediawiki.org/wiki/Hosting_services

[jeroen3]

Ik ben benieuwd wat hier uit komt, want hier is ook een ernstig tekort aan dit soort informatie.
We hebben wel al enkele jaren een wiki, maar dat vinden mensen "te ingewikkeld".

Want (@Arie-) mediawiki is ook een aardig complex pakket, dat is anders dan wysiwyg google docs bestandje.
Iets schrijven is ook wel een kunstje, ondanks dat er een wysiwyg editor is moet je een hoop typische mediawiki dingen doen met plaatjes, keyword e.t.c.

Er zijn wel diensten die wat meer managed wiki-achtige dingen aanbieden, die zijn wel relatief kostbaar.
Zoals Nuclino.

Prusa's assembly manuals zijn gemaakt met Duzoki, ze lezen wel goed. (heeft ifixit ook volgens mij)
Is alleen "ask us for pricing" dus dat zal onbetaalbaar zijn, en USA based.

[P_de_B]

Bovenstaande lijkt me allemaal erg complex en gericht op technische mensen? Ik zou kijken naar iets als https://www.selfguide.com/

[Oon]

Ik zou kijken naar Docmost, is een tool die je kunt self-hosten en gericht is op wiki maar ook specifiek op documentatie.

[Anoniem: 80910]

P_de_B schreef op donderdag 29 augustus 2024 @ 12:56:
Bovenstaande lijkt me allemaal erg complex en gericht op technische mensen? Ik zou kijken naar iets als https://www.selfguide.com/

700 euro per maand, vanafprijs

[P_de_B]

Anoniem: 80910 schreef op donderdag 29 augustus 2024 @ 13:43:
[...]


700 euro per maand, vanafprijs

Ja, en? Als het verder aan alle eisen voldoet lijkt me dat prima

[RobIII]

P_de_B schreef op donderdag 29 augustus 2024 @ 14:12:
[...]

Ja, en? Als het verder aan alle eisen voldoet lijkt me dat prima

To be fair: als ik punt 4 zie denk ik dat €700 p/maand daar onder valt Archbee viel ook al af.

[ Voor 9% gewijzigd door RobIII op 29-08-2024 14:26 ]

[P_de_B]

RobIII schreef op donderdag 29 augustus 2024 @ 14:25:
[...]

To be fair: als ik punt 4 zie denk ik dat €700 p/maand daar onder valt Archbee viel ook al af.

Ik kan in niemands portemonnee kijken en het is nogal subjectief wanneer een tarief boven 'MKB' uitstijgt, maar als je hiermee uren personeel en helpdesk terugverdient kan het de moeite waard zijn.

Ik denk dat van alle criteria prijs nog wel eens het meest eenvoudig aan te passen is.

[Voutloos]

Ik weet niet of er een optie bestaat met alle 8 de eisen, maar als je 1 los laat kan er wel iets..
Bijvoorbeeld Europees bedrijf beperkt flink. Dat je voor je core business die eis hebt is 1 ding, maar documentatie zou veel minder privacygevoelig o.i.d. moeten zijn, dus misschien wel acceptabel? Etc.

[Skyaero]

Een hoop reacties. @Arie- legt het probleem goed uit en waarom de devs daar zich niet bezig moeten houden.

@P_de_B suggestie van Selfguide zit in de goede richting, alleen met een vanafprijs van 8.5k per jaar wel gericht op enterprise en daarmee boven budget.

Blijkt toch lastiger te zijn dan ik dacht en de opties vallen me nogal tegen. Alsof er een gat in de markt zit. De verschillende suggestie en discussie geven wel aan dat de eisen misschien te strikt zijn en we, zoals @Voutloos suggereert, misschien iets flexibeler moeten zijn.

De suggestie van een wiki is nu een aantal keren naar voren gekomen. Die is relatief makkelijk zelf te hosten (bijv via Azure Marketplace), of via managed hosting - voldoende Europese bedrijven (o.a. mywikis europe) die dit aanbieden.

Ik ben wel benieuwd waar @jeroen3 dan tegenaan loopt. Is het de lezer of de schrijver die het te ingewikkeld vindt?

[P_de_B]

Skyaero schreef op donderdag 29 augustus 2024 @ 15:03:


De suggestie van een wiki is nu een aantal keren naar voren gekomen. Die is relatief makkelijk zelf te hosten (bijv via Azure Marketplace), of via managed hosting - voldoende Europese bedrijven (o.a. mywikis europe) die dit aanbieden.

Je probleem is denk ik niet de techniek, maar het juist vullen, up to date houden en toegankelijk en gebruikersvriendelijk laten zijn. Ik kan me voorstellen dat 8K te veel is, maar met een wiki installeren los je m.i. niet je probleem op.

[jeroen3]

@Skyaero de schrijvers vooral. Ik merk het zelf ook wel, het kost net wat meer effort.
Met als gevolg dat de niet-programmeurs nu in een ClickUp doc schrijven, wat weer heel slecht vindbaar is.
Ik ook te maken heb met "waarom zou ik dat opschrijven, ik weet toch hoe het werkt" cultuur.

Lezen van mediawiki heeft ook drempels, je moet namelijk een account aanmaken en dat is anders dan de gemiddelde ervaring nu. We hebben hosted bij mywikis.eu, wellicht is hun instance niet de makkelijkste?

Docmost zit er interessant uit. Helaas is self-hosted niet hier niet zomaar mogelijk...

[ Voor 9% gewijzigd door jeroen3 op 29-08-2024 15:13 ]

[joke_name]

Waarom niet koppelen met bijvoorbeeld je helpdesk systeem.

Dus bijvoorbeeld Zendesk artikelen die je kan raadplegen maar bijvoorbeeld in kan zoeken.

[Anoniem: 80910]

*snip* nergens voor nodig, er zijn talloze hosts te vinden met een simpele zoekopdracht * deze prijzen zijn veel schappelijker dan 700 per maand.

Hoe wil je de documentatie beschikbaar maken ? Via de saas of op een ander domein ?
Want via saas heb je ook nog dat je wellicht iets moet maken om die documenten op te halen van de andere server.

[ Voor 26% gewijzigd door RobIII op 29-08-2024 17:11 ]

[ghostman]

Nog 2 andere mogelijke oplossingen, die alleen niet helemaal voldoen aan je eisen:

- WikiJS: Wel selfhosted, dus beheer is in eigen handen.
- Notion: Officieel gevestigd in de VS dacht ik, maar voor 10EU per maand met een eigen domein.

[4maself]

Bookstack kan ook interessant zijn.

Of als het bedrijf niet zelf wil hosten, doet bijvoorbeeld StellarHosted of Elest IO dat ook voor je.

[Anoniem: 80910]

je zoekopdracht bevat niet alleen europeesche hosting, maar goed, ik snap niet zozeer dat ik geen voorbeeld mag geven terwijl er wel voorbeelden gegeven worden van 700 euro?.

ik wou alleen maar aangeven, dat er bij een prijs van nog geen 5 euro per maand je al een aardig pakket krijgt vandaag de dag. Die informatie ontbrak nu.

Bij de andere methode kun je nog AI gebruiken in de app, dat kost 100 dollar per jaar

[2400baud]

Nog een suggestie die ws voldoet aan de eisen:

- Proware https://www.metaware.nl

[joca]

Het werd al eerder genoemd maar diverse ticketsystemen hebben ook een documentatie/knowledge base optie. Zendesk werd genoemd maar er zijn er meer, freshdesk is wellicht een (goedkopere) optie al is dat ook geen eu partij naar mijn weten.

Bookstack kwam voorbij, mooie tool maar ik denk voornamelijk voor interne documentatie, je zal het ook zelf moeten hosten.

[ValHallASW]

Een beetje ouderwets gedacht wellicht, maar: Word en naar .pdf exporteren en op je platform (of: op Sharepoint) hosten? Voldoet (oké, met een beetje fudgen) aan al je eisen:

- Doelgroep voor de documentatie is de (niet-technische) gebruiker van de saas-software, denk niveau projectmanager -> mensen snappen PDF
- De gebruiker van de documentatie-software heeft niet per se een developer-achtergrond. Dus geen git-achtige dingen. Bij voorkeur WYSIWYG. Markdown is misschien nog wel aan te leren. -> word met sharepoint/onedrive als version control/backup
- Online dienst, dus niets zelf hoeven te installeren. -> Word heb je al.
- Gericht op MKB, we hebben geen Enterprise budget -> Word heb je al.
- Europees bedrijf -> Je host het zelf
- Koppelen van een eigen domeinnaam -> Niemand zit waar je pdfje gehost wordt.
- navigatiefuncties zoals zoekbalk zijn zeer gewenst -> ctrl-f zit in elke pdf reader
- Publiek toegankelijk en privaat beheerd -> check