Jak najlepiej projektować dokumenty projektowe?

Question

Wcześniej dyskutowano na temat SO (here i here), w jaki sposób można powielać wersje dokumentów biurowych, jednak myślę, że moje pytanie jest wciąż trochę inne.

Moje projekty programistyczne rozpoczynają się od pustego folderu projektu, z wyjątkiem podfolderu o nazwie "Dokumenty projektowe", który zawiera szkic specyfikacji funkcjonalnej projektu, a następnie jest rozszerzany, aby zawierał specyfikacje API lub cokolwiek innego jest potrzebne .

Oczywiście sprawdzam również te pliki w SVN. Czego szukam to dobre formaty plików i strategie, aby dobrze bawić się z całym procesem wersjonowania, różnicowania i łączenia. Na przykład, myślę, że najlepiej byłoby przechowywać pliki z procesorem tekstu jako XML, czy też różnice byłyby brzydkie i bezużyteczne dla czytelników? Oto, co chciałabym zrobić:

• diff i scalania dokumentów tekstowych (must-have OOO, nice-to-mieć MS Word)
• diff (a może połączyć, choć to może się okazać koncepcyjnie trudne) rysunki schematów, takie jak diagramy UML. Myślałem, że mogą to być niezależne pliki XML/SVG i być połączone z dokumentami tekstowymi, ale nie wiem wystarczająco dużo o tym, jak działają te dokumenty, aby stwierdzić, czy jest to rzeczywiście możliwe.
• pokaż uaktualniany numery wersji wewnątrz dokumentów tekstowych (być może z svn:keywords)

Czy ktoś zrobić tego rodzaju rzeczy już? Istnieje prawdopodobnie pewna liczba dokumentacji i samouczków dotyczących plików OOo itp., Które mogłem sprawdzić, ale jednocześnie doceniam wskazówki dla nich, szukam głównie relacji z pierwszej ręki o rzeczach, które w praktyce działały lub nie działały.

---

Edit: Wystarczy, aby upewnić się, nie ma „użytkowników nietechnicznych” zaangażowane tutaj. To tylko programiści, a dokumenty są przeznaczone tylko do programowania. Mogą być publikowane pliki PDF, ale to będzie tylko kolejny artefakt budujący, nic, co musi być wersjonowane.

Nadal nie możemy naprawdę chcesz używać Tex lub tym podobne. Wiem, że to jest świetne i wszystko, ale po prostu nie mogę się martwić o prosty dokument tekstowy. Musielibyśmy się tego nauczyć, zebrać wszystkie dodatkowe pakiety, dodać rendering Tex-to-PDF do naszego procesu budowania itd. Byłoby to trochę projektem programistycznym tylko dla dwóch lub trzech dokumentów. Jeśli cokolwiek, wolałbym używać HTML, ale procesor tekstu nadal wydaje mi się dobrą opcją, oprócz tego, że chcę dobrej wersji.

Jest jeszcze jedna myśl: czy jest coś takiego jak wtyczka SVN dla OOo lub na odwrót? Lub nawet, co by było, aby dodać obsługę SVN do OOo? Podobnie jak opcja "Synchronizuj" w menu Plik i pole tekstowe "Numer wersji". Chodzi mi o to, że nie byłoby to częścią naszej firmy, ale byłoby fajnie, a przecież jestem szefem.

Answer 1

Problem z OOo polega na tym, że format pliku to skompresowana na zip grupa plików (spróbuj zmienić rozszerzenie pliku na .zip lub .7z). To sprawia, że ​​trudno jest robić różnice.

Spoglądam na LaTex i DocBook, ale ustalenie szablonu stylu do użycia jest dość trudne. Jest to trudna część wszystkich tutoriali.

Więc w zasadzie zrezygnowałem z otrzymywania znaczących różnic z dokumentacji. Zostaje on sprawdzony jako binarne obiekty blob.

Answer 2

Gdy to możliwe, wszystkie pliki "surowe" przechowuję w formacie tekstowym (tj. XML/DocBook, zwykły tekst, LaTeX) oprócz renderowanych plików PDF pod kontrolą wersji wersji. Ponadto próbuję użyć numeru wersji repozytorium Subversion jako numeru wersji dokumentu.

Jeśli nie możesz użyć automatycznego numeru wersji (tj. W dokumencie Word), zalecamy użycie daty ostatniej modyfikacji. Upewnij się, że używasz daty ostatniej edycji, a nie aktualnego makra daty, ponieważ makro bieżącej daty wypełni dowolną datę, kiedy jest drukowany, co prawdopodobnie nie jest tym, czego potrzebujesz. Innym sposobem jest oczywiście użycie tradycyjnego przyrostowego numeru wersji, ale z mojego doświadczenia wynika, że ​​ludzie często mają problem ze sprawdzeniem, która wersja jest najnowsza, gdy widzimy tylko numer. Ludzie są zwykle bardziej świadomi starych dat.

uwzględniając datę i/lub numer wersji jako część nagłówka/stopki na każdej stronie jest również duży plus, w ten sposób można uniknąć ludzi mieszających się różne wersje leżące wokół na ławkach ...

Answer 3

Redaktorzy WYSIWYG (Word, OpenOffice) zazwyczaj nie widzą powodu, dla którego ktokolwiek inny powinien zadzierać z ich plikami, więc znalezienie edytora, który nie jest technicznym użytkownikiem może używać i, który jest przyjazny dla systemu kontroli wersji, jest niemożliwy. Wyjątek: git ma numer filter which can look into OpenOffice files. Nie jestem jednak pewien, czy możesz użyć rozszerzenia słów kluczowych.

Proponuję wykorzystać wiki i tydzień szkolenia dla użytkowników, jak z niego korzystać. Rozwiązuje wszystkie twoje problemy (niektóre wiki można nawet sprawdzić w systemie kontroli wersji). Jak już wspomniałem w different post, jedyną przeszkodą jest to, że użytkownicy poświęcą kilka dni na przyzwyczajenie się do tego pomysłu. Potem pokochają to.

Answer 4

Używamy wiki do dokumentacji niektórych naszych projektów. Ma świetne śledzenie wersji dla każdego wpisu, ale nie na poziomie dokumentu, więc wyeksportowaliśmy dokumenty i sprawdziliśmy je również dla linii podstawowych.

Answer 5

Jak zauważył Aaorn Digulla, wiki to świetny pomysł. Musisz zdać sobie sprawę, że jedynym sposobem, w jaki naprawdę chcesz osiągnąć to, co chcesz, jest ponowne przemyślenie całej strategii dokumentu.

Żadne oprogramowanie nie rozwiąże problemu niezgodnych formatów plików i nie będzie w stanie porównać różnych wersji. Narzędzia, których teraz używasz są niewłaściwymi narzędziami do pracy. To będzie trudne, niewygodne i być może drogie, aby zmienić zestaw narzędzi i sposób myślenia, ale to jest koszt osiągnięcia tego, co chcesz, co w efekcie skończy 10 lat.

Wystarczy pomyśleć o trudnościach, które początkowo miały miejsce w przypadku dokumentów schematów, diagramów UML, a nawet czegoś tak prostego, jak planowanie dokumentu Word. Te zadziałały do ​​tego momentu i dotarły aż tak daleko, ale jedyną realną drogą jest przejście do narzędzi, które zostały zaprojektowane pod kątem tego, co jest potrzebne, aby uzyskać teraz teraz.

Uwaga: ostatecznym rozwiązaniem może nie być wiki, ale zdecydowanie nie jest to, czego teraz używasz. Musisz trochę zbadać i wypróbować kilka rzeczy.

Answer 6

Wygląda na to, że wiki jest dobrym pomysłem, ale jeśli to nie pasuje, możesz rozważyć użycie Sphinx (lub podobnego) z ReStructured Text.

Chociaż byłby to również "mały projekt programistyczny", zapewniałby HTML jako wyjście przy zachowaniu ładowności i czytelności różnic. Ustawienie tego byłoby, jak sądzę, mniejszym wysiłkiem niż w przypadku LaTeX; krzywa uczenia się byłaby znacznie mniejsza; a jeśli potrzebujesz LaTeXa i PDF-ów w przyszłości, czekają na Ciebie.

Answer 7

Klient TortoiseSVN (Windows) dla SVN wie wystarczająco dużo o Open Office, że gdy poprosisz go o ich sprawdzenie, po uzyskaniu wymaganych wersji, otworzy Office z obydwoma otwartymi dokumentami, pokazując różnice. Używam tego bardzo. Wyobrażam sobie, że istnieją nawet bardziej atrakcyjne rozwiązania i podobne rzeczy dla Mac/Linux/OS/360 lub innego, ale dla tego bardzo technicznego użytkownika, który często czuje się bardzo nie-techniczny, ponieważ chce zjeść lunch, TortoiseSVN (http://tortoisesvn.tigris.org/) dostarcza.