SL reseplanerare, dokumentation otydlig

Hej,
api-dokumentationen för sl reseplanerare är väldigt otydlig. Det verkar som att man gått efter filosofin "mer text gör det tydligare" när den skrivits. Jag håller inte med.

Det känns som ett dokument fullt av utspridda tips. Det är inte styckeindelat (om man inte räknar precis varenda mening som eget stycke) och saknar rubriker (men fullt av fetstil som inte är rubriker), så intrycket är att om man vill få reda på något måste man läsa allt från början till slut. Det går alltså inte att slå upp/hitta det man är intresserad av. Tipsen är också ganska svårlästa: "använd antingen S eller SID och Z eller ZID".

Man får inget sammanhang när alla parametrar presenteras, utan det får man bara om man tar sig igenom alla specifika exempel. Varför inte göra ett lättförståeligt regexp-exempel av en URI istället för specifika exempel? Till och med BNF hade varit att föredra.

Sammanfattningsvis är problemet att allt är utspritt och oöversiktligt så att man måste rulla fram och tillbaka i dokumentet för att förstå något. 70% av all text kan ersättas av en bra tabell där man faktiskt samlar all info om varje parameter. Resten kan styckeindelas och få rubriker...