Ask HN: Future proof project documentation?

1 points by dktoao ↗ HN
I have been tasked with coming up with ideas for the best way to migrate a very large and very fragmented documentation base spanning 30+ years to a more manageable system. The current documentation is in every proprietary file format / cloud system imaginable (Lotus Notes, GDoc, SharePoint, shared network folders).

In my dreams I would like everyone to start maintaining all documentation in plain text (markdown probably?), checked in the same repository as the source code, with possibly a simple cron job to convert everything to a static html webpage every night. While I think this is the best system, discussing casually with colleagues (mostly EE, not CS) has revealed the following roadblocks to my plan:

1. Reluctance to learn Markdown, which is seen as a new fancy technology to learn. Given the math heavy lean of the documentation, and the mess that is Latex math notation, is sort of understandable. Also, I am worried about the lack of a standard for Markdown, but I like how instant it is to learn.

2. Limited knowledge on the team of the small amount of web technology that it would take to maintain this infrastructure.

The last thing that I want to do is to go back to a proprietary platform as our IT group pulls this rug out on us every ~5 years. I tried a web search but mostly came up with quick buzz-word heavy blogs and landing pages for proprietary systems.

Does anyone have any experience doing this for documentation? What are the drawbacks? Are there any pitfalls that I am missing that make this a foolish idea? Any high quality resources or blog posts that I can take ideas from?

Thanks in advance!

0 comments

[ 3.3 ms ] story [ 13.3 ms ] thread

No comments yet.