Đôi khi không chỉ bản thân tài liệu mà cả quá trình làm việc với nó cũng có thể rất quan trọng. Ví dụ, trong trường hợp các dự án, phần lớn công việc liên quan đến việc chuẩn bị tài liệu và một quy trình không chính xác có thể dẫn đến sai sót và thậm chí mất thông tin, do đó, mất thời gian và lợi ích. Nhưng ngay cả khi chủ đề này không phải là trọng tâm công việc của bạn và nằm ở ngoại vi, quy trình phù hợp vẫn có thể cải thiện chất lượng tài liệu và giúp bạn tiết kiệm thời gian.
Cách tiếp cận được nêu ở đây, với , có rào cản gia nhập thấp. Về mặt kỹ thuật, ngày mai bạn có thể bắt đầu làm việc theo cách mới.
Báo cáo sự cố
Bạn cần tạo một tài liệu hoặc bộ tài liệu. Có lẽ đây là tài liệu dự án hoặc nhật ký mạng của bạn hoặc thứ gì đó đơn giản hơn, chẳng hạn như bạn phải mô tả các quy trình trong công ty hoặc trong bộ phận của mình. Nói chung, chúng ta đang nói về bất kỳ tài liệu hoặc bộ tài liệu nào có văn bản, hình ảnh, ký hiệu... Hãy làm phức tạp nhiệm vụ bởi thực tế là
- công việc này liên quan đến công việc chung, nỗ lực của một nhóm hoặc một số nhóm nhân viên
- Do đó, bạn muốn có một tài liệu ở một định dạng nhất định, với các thuộc tính kiểu dáng công ty, được tạo theo một mẫu nhất định. Để cụ thể, chúng tôi sẽ cho rằng đây là MS Word (.docx)
10 năm trước, cách tiếp cận này rất đơn giản: chúng tôi đã tạo một hoặc nhiều tài liệu MS Word và bằng cách nào đó đã tổ chức công việc thay đổi.
Và cách tiếp cận này vẫn còn hiệu lực. Nó cũng được các nhà tích hợp lớn sử dụng khi tạo tài liệu dự án. Nhưng bằng trực giác, có thể thấy rõ rằng nếu bạn thực sự làm việc chuyên sâu trên một tài liệu, có nhiều chỉnh sửa và thảo luận trong một thời gian dài, thì cách tiếp cận này không thuận tiện cho lắm.
Ví dụ
Tôi cảm nhận được vấn đề này khá sâu sắc khi làm việc cho một nhà tích hợp lớn. Quá trình thay đổi tài liệu thiết kế như sau:
- kỹ sư tải xuống phiên bản mới nhất của tài liệu MS Word (.docx)
- thay đổi tên
- thực hiện các thay đổi để theo dõi thời trang
- gửi tài liệu có chỉnh sửa cho kiến trúc sư
- cũng gửi danh sách tất cả các chỉnh sửa kèm theo nhận xét
- kiến trúc sư phân tích những thay đổi
- nếu mọi việc đều ổn, nó sẽ sao chép những thay đổi này vào một tệp có phiên bản mới nhất, thay đổi phiên bản và tải nó lên tài nguyên được chia sẻ
- nếu có ý kiến, một cuộc thảo luận sẽ được bắt đầu (email hoặc cuộc họp)
- đạt được sự đồng thuận
- điểm tiếp theo 3 - 9
Tuy công việc không căng thẳng nhưng bằng cách nào đó vẫn có hiệu quả. Nhưng đến một thời điểm nhất định, quá trình này lại trở thành điểm nghẽn của toàn bộ dự án và dẫn đến nhiều vấn đề. Vấn đề là mọi thứ trở nên tồi tệ ngay khi có nhiều đội thực hiện thay đổi thường xuyên và đồng thời.
Vì vậy, khi chúng tôi chuyển sang giai đoạn thử nghiệm sơ bộ, nhiều vấn đề khác nhau bắt đầu xuất hiện và mặc dù chỉ ở những khía cạnh nhỏ nhưng cần phải thay đổi tài liệu thường xuyên - bốn nhóm khác nhau, mỗi ngày, gần như đồng thời, thảo luận. Tất cả những thay đổi này diễn ra thông qua một kỹ sư - một kiến trúc sư. Tệp thiết kế dự án rất lớn và kết quả là kiến trúc sư bị choáng ngợp với công việc thường ngày liên quan đến việc sao chép, chỉnh sửa nhiều, mắc nhiều sai sót, phải kiểm tra lại mọi thứ rồi gửi lại, và nói chung là gần như hoàn thành. sự hỗn loạn.
Trong trường hợp này, cách tiếp cận này, cách tiếp cận làm việc trên tài liệu MS Word, gặp rất nhiều khó khăn và tạo ra nhiều vấn đề.
Git, Markdown
Đối mặt với vấn đề được mô tả trong ví dụ trên, tôi bắt đầu nghiên cứu vấn đề này.
Tôi thấy rằng việc sử dụng cùng với khi tạo tài liệu.
Git là một công cụ phát triển. Nhưng tại sao không sử dụng nó cho quá trình tài liệu? Trong trường hợp này, vấn đề làm việc của nhiều người dùng sẽ được giải quyết. Nhưng để tận dụng tối đa khả năng của Git, chúng ta cần một định dạng tài liệu văn bản, chúng ta cần tìm một công cụ khác ngoài MS Word và Markdown rất phù hợp cho những mục đích này.
Markdown là một ngôn ngữ đánh dấu văn bản đơn giản. Nó được thiết kế để tạo ra các văn bản được thiết kế đẹp mắt trong các tệp TXT thông thường. Nếu chúng tôi tạo tài liệu của mình trong Markdown thì sự kết hợp Markdown - Git sẽ trông tự nhiên.
Và mọi thứ sẽ ổn, và tại thời điểm này, chúng ta có thể chấm dứt nó, nếu không có điều kiện thứ hai: “kết quả là, chúng ta cần một tài liệu ở một định dạng nhất định, với các thuộc tính của phong cách công ty, được tạo theo một mẫu nhất định” (và ngay từ đầu chúng tôi đã đồng ý rằng chắc chắn đó sẽ là MS Word). Nghĩa là, nếu chúng ta quyết định sử dụng Markdown, thì bằng cách nào đó chúng ta cần chuyển đổi tệp này thành .docx thuộc loại được yêu cầu.
Có các chương trình để chuyển đổi giữa các định dạng khác nhau, ví dụ: .
Bạn có thể chuyển đổi tệp Markdown sang định dạng .docx bằng chương trình này.
Tuy nhiên, bạn vẫn cần hiểu rằng, thứ nhất, không phải mọi thứ có trong Markdown sẽ được chuyển đổi sang MS Word và thứ hai, MS Word là cả một quốc gia so với thị trấn mảnh mai nhưng vẫn nhỏ bé, Markdown. Có một lượng lớn mọi thứ có trong Word mà không có ở bất kỳ dạng nào trong Markdown. Bạn không thể tiếp tục và chuyển đổi định dạng Markdown của mình sang định dạng MS Word mong muốn bằng cách sử dụng một số khóa Pandoc nhất định. Vì vậy, thông thường, sau khi chuyển đổi, bạn phải “chỉnh sửa” tài liệu .docx thu được theo cách thủ công, việc này có thể tốn thời gian và dẫn đến sai sót.
Nếu chúng ta có thể viết một đoạn script tự động “hoàn thành” những gì Pandoc không thể xử lý thì đó sẽ là một giải pháp lý tưởng.
Do chức năng của MS Word và Markdown không xác định được nên tôi nghĩ không thể giải quyết vấn đề này nói chung, nhưng liệu điều này có thể thực hiện được trong những tình huống cụ thể, yêu cầu cụ thể không? Kinh nghiệm của tôi cho thấy rằng có, điều đó là có thể và rất có thể là có thể xảy ra đối với nhiều người, hoặc thậm chí có thể là hầu hết các tình huống.
Giải pháp của một vấn đề cụ thể
Vì vậy, trong trường hợp của tôi, sau khi chuyển đổi tệp bằng Pandoc, tôi phải xử lý tệp bổ sung theo cách thủ công, cụ thể là
- thêm trường vào Word bằng cách tự động đánh số đầu đề (chú thích) của bảng, hình ảnh
- thay đổi kiểu bàn
Tôi chưa tìm thấy cách thực hiện việc này bằng cách sử dụng tiêu chuẩn (Pandoc) hoặc các phương tiện đã biết. Vì vậy, tôi đã áp dụng tập lệnh python với bưu kiện. Kết quả là tôi đã được tự động hóa hoàn toàn. Bây giờ tôi có thể chuyển đổi tệp Markdown của mình thành dạng tài liệu MS Word mong muốn bằng một lệnh.
Xem chi tiết .
Ghi chú:
Tất nhiên, trong ví dụ này, tôi chuyển đổi một số tệp Markdown trừu tượng, nhưng cách tiếp cận tương tự đã được áp dụng cho tài liệu "chiến đấu" và kết quả tôi nhận được gần như giống hệt tài liệu MS Word mà chúng tôi đã nhận được trước đó bằng định dạng thủ công .
Nói chung, với pywin32, chúng tôi gần như có toàn quyền kiểm soát tài liệu MS Word, điều này cho phép chúng tôi thay đổi và đưa nó về dạng mà tiêu chuẩn công ty của bạn yêu cầu. Tất nhiên, những mục tiêu tương tự có thể đạt được bằng cách sử dụng các công cụ khác, chẳng hạn như macro VBA, nhưng tôi sử dụng python sẽ thuận tiện hơn.
Một công thức ngắn gọn cho phương pháp này:
Markdown + Git -- (нечто) --> MS WordKhông quan trọng "cái gì đó" là gì. Trong trường hợp của tôi, đó là Pandoc và python với pywin32. Sở thích của bạn có thể khác nhau, nhưng điều quan trọng là điều đó có thể thực hiện được. Và đây là thông điệp chính của bài viết này.
Tóm lại, ý tưởng là với phương pháp này, bạn chỉ làm việc với tệp Markdown và sử dụng Git để cộng tác và kiểm soát phiên bản, đồng thời chỉ khi cần thiết (ví dụ: để cung cấp tài liệu cho khách hàng) mới tự động tạo tệp ở định dạng mong muốn ( ví dụ MS Word).
quá trình
Tôi nghĩ rằng đối với nhiều người, công thức đưa ra ở trên là đủ để hiểu cách tổ chức quy trình làm việc với tài liệu. Tuy nhiên, tôi vẫn thường tập trung vào các kỹ sư mạng, vì vậy tôi sẽ trình bày một cách khái quát về quy trình làm việc hiện tại trông như thế nào và điều này khác với cách tiếp cận chỉnh sửa tệp MS Word như thế nào.
Cụ thể, chúng tôi sẽ chọn GitHub làm nền tảng để làm việc với Git. Sau đó, bạn nên tạo một kho lưu trữ và đặt tệp Markdown hoặc các tệp bạn dự định làm việc trong nhánh chính.
Chúng ta sẽ xem xét một quy trình đơn giản dựa trên "luồng github". Mô tả của nó có thể được tìm thấy cả trên Internet và trên .
Giả sử có bốn người đang làm việc trên tài liệu và bạn là một trong số họ. Sau đó, bốn nhánh bổ sung được tạo ra, chẳng hạn như tên của những người này. Mọi người đều làm việc tại địa phương, trong chi nhánh của mình và thực hiện các thay đổi cần thiết .
Sau khi hoàn thành một số phần công việc đã hoàn thành, bạn tạo một yêu cầu kéo, từ đó bắt đầu cuộc thảo luận về những thay đổi của mình. Có lẽ, trong quá trình thảo luận, bạn nên thêm hoặc thay đổi điều gì đó khác. Trong trường hợp này, bạn thực hiện những thay đổi cần thiết và tạo yêu cầu kéo bổ sung. Cuối cùng, những thay đổi của bạn được chấp nhận và hợp nhất vào nhánh chính (hoặc bị loại bỏ).
Tất nhiên, đây là một mô tả khá chung chung. Để tạo một quy trình chi tiết, tôi khuyên bạn nên liên hệ với các nhà phát triển của bạn hoặc tìm những người hiểu biết. Nhưng tôi muốn lưu ý rằng rào cản gia nhập Git khá thấp. Điều này không có nghĩa là giao thức đơn giản nhưng bạn có thể bắt đầu đơn giản. Nếu bạn chưa biết gì cả, tôi nghĩ sau khi dành vài giờ hoặc có thể vài ngày để tìm hiểu và cài đặt, bạn có thể bắt đầu sử dụng nó.
Lợi ích của phương pháp này so với quy trình được mô tả trong ví dụ trên là gì?
Trên thực tế, các quy trình khá giống nhau, bạn chỉ cần thay thế
sao chép một tập tin -> tạo một nhánh
sao chép văn bản vào tệp cuối cùng -> hợp nhất
sao chép những thay đổi mới nhất cho chính bạn -> git pull/fetch
thảo luận trong thư từ -> kéo yêu cầu
chế độ theo dõi -> git diff
phiên bản được phê duyệt mới nhất -> chi nhánh chính
sao lưu (sao chép vào máy chủ từ xa) -> git Push
...
Do đó, bạn đã tự động hóa mọi việc bạn đã phải làm nhưng theo cách thủ công.
Ở cấp độ cao hơn, nó cho phép bạn
- tạo ra một quy trình rõ ràng, đơn giản và được kiểm soát để thay đổi tài liệu
- bởi vì bạn tự động tạo tài liệu cuối cùng (trong ví dụ MS Word của chúng tôi), điều này giúp giảm khả năng xảy ra lỗi định dạng
Ghi chú:
Như đã nói, tôi nghĩ rõ ràng là ngay cả khi bạn chỉ làm việc trên tài liệu, việc sử dụng Git có thể giúp công việc của bạn dễ dàng hơn rất nhiều.
Tất cả điều này cải thiện chất lượng của tài liệu và giảm thời gian tạo ra nó. Và một phần thưởng nhỏ khác - bạn sẽ học Git, điều này sẽ giúp bạn khi tự động hóa mạng của mình :)
Làm thế nào để chuyển sang một quy trình mới?
Ở đầu bài viết, tôi đã viết rằng ngày mai bạn có thể bắt đầu làm việc theo cách mới. Làm thế nào để đưa công việc của bạn theo một hướng mới?
Đây là trình tự các bước mà rất có thể bạn sẽ cần phải tuân theo:
- nếu tài liệu của bạn rất lớn, hãy chia nó thành nhiều phần
- chuyển đổi từng phần thành Markdown (sử dụng Pandoc chẳng hạn)
- cài đặt một trong các trình soạn thảo Markdown (tôi sử dụng )
- rất có thể bạn sẽ phải điều chỉnh lại định dạng của tài liệu Markdown đã tạo
- bắt đầu áp dụng quy trình được mô tả ở chương trước
- đồng thời bắt đầu sửa đổi tập lệnh chuyển đổi cho phù hợp với nhiệm vụ của bạn (hoặc tạo một cái gì đó của riêng bạn)
Bạn không cần phải đợi cho đến khi tạo và hoàn thiện cơ chế chuyển đổi Markdwon -> loại tài liệu đầu ra được yêu cầu. Vấn đề là, ngay cả khi bạn không thể nhanh chóng tự động hóa hoàn toàn quy trình chuyển đổi tệp Markdown của mình, bạn vẫn có thể thực hiện việc đó ở một số dạng bằng cách sử dụng Pandoc và sau đó đưa nó đến dạng cuối cùng theo cách thủ công. Thông thường, bạn không cần phải làm điều này thường xuyên mà chỉ khi kết thúc một số giai đoạn nhất định và công việc thủ công này, mặc dù bất tiện, nhưng theo tôi, vẫn khá chấp nhận được ở giai đoạn gỡ lỗi và không nên “làm chậm” quá trình nhiều.
Mọi thứ khác (Markdown, Git, Pandoc, Typora) đã sẵn sàng và không cần nhiều nỗ lực hay thời gian để bắt đầu làm việc với chúng.
Nguồn: www.habr.com
