Nie zmuszaj ich do czytania. Nie jestem pewien, czy można to zastosować bezpośrednio do Twojej obecnej sytuacji. To, co mnie wyróżnia, to to, że chcesz, aby ludzie mogli stać się ekspertami w danym problemie za pierwszym razem lub kontynuować czytanie, dopóki nie zrozumieją. To nowość, ale tak jak tego doświadczasz, mało prawdopodobne. Prawdopodobnie nie ma na to czasu.
Myślę, że dobrą rzeczą, którą możesz zrobić, jest diagramowanie lub narysowanie czymkolwiek te rzeczy są, zamiast próbować opisać je tekstowo i wszystkie zawiłości.
Pracuję z wieloma elementami strony internetowej i czasami te elementy mogą mieć wiele podstawowych zasad biznesowych i przypadków narożnych. Czasy, w których generowanych jest najwięcej defektów, to sytuacje, w których musimy zbudować na podstawie wielkiej historii użytkownika wymiotów, która zawiera mnóstwo wymagań, co oznacza, że nawet jeśli przeczytasz, ponownie przeczytasz, a nawet przeczytasz jeszcze raz, prawdopodobnie przegapisz coś kluczowego.
W jednym projekcie mieliśmy historie użytkowników, które faktycznie kolidowały z dokumentem projektu graficznego. Najczęściej to, co faktycznie zostało wdrożone, zostało wdrożone zgodnie z dokumentacją projektową, ponieważ można to było zrozumieć znacznie łatwiej i na pierwszy rzut oka. Miał wykresy przepływu, makiety interfejsu użytkownika i oczekiwaną funkcjonalność, ale źródłem prawdy miała być rzeczywista historia użytkownika, mimo że były one znacznie trudniejsze do odczytania.
Więc pierwszą rzeczą, która moim zdaniem pomogłaby, jest próba nakłonienia wszystkich do tablicy tych procesów i udokumentowania ich graficznie, zamiast pisania długich, nudnych tomów tekstu.
Zacząłem pracować z biblioteką o nazwie Rx, która zajmuje się danymi hydraulicznymi w funkcjonalny, reaktywny sposób. Czytałem dokumenty o tym, jak powinna działać hydraulika, dopóki nie zsiniałem. Jednak to, co naprawdę sprawiło, że całość się zatrzasnęła, to marmurowe diagramy wyjaśniające, jakie dane trafiają, gdzie, kiedy i dlaczego. Te diagramy są częścią podstawowej dokumentacji, a każdy operator / funkcja w bibliotece ma diagram, który odpowiada tekstowemu wyjaśnieniu funkcji, dzięki czemu możesz szybko zrozumieć rzecz, którą próbujesz zrozumieć, nawet jeśli tylko przeglądasz .
Skorzystaj z tego i spróbuj znaleźć sposób, aby widoki z lotu ptaka dawały wystarczająco dobry punkt widzenia na to, nad czym pracujesz, ale także zachęcają do czytania szczegółowego opisu. Mówisz, że niektóre z rzeczy, które próbujesz wyszczególnić, są takimi rzeczami, jak dowody matematyczne. Myślę, że musi istnieć sposób, aby opisać te rzeczy „w akcji” lub zastosować w taki sposób, aby ktoś mógł uzyskać pełne zrozumienie tego pojęcia użyj długiego opisu tekstowego, aby w pełni zrozumieć, co się dzieje.
Może po prostu lubię książki ze zdjęciami.