
Ask HN: What tools and approaches to use for project documentation? - chrismcv
I work for an SME currently reviewing our methodology for projects delivered to 3rd party clients (B2B). We do a small number of projects per year (&lt; 5), and might be 6-12 months effort. A project is usually based on the delivery of our product, and some extensions to it specific to that customer.<p>Having completed a recent project, and done a post-mortem, there are some areas that I think we can improve on, but there doesn’t seem to be a solution that I’m totally happy with.<p>Requirements  - for previous project, we have around 400, these were delivered to the client in tables in an MS Word document, though for internal use, they lived in a google docs spreadsheet as well. We debated whether these could live in our issue tracker (currently Jetbrains YouTrack) but could come up with a straightforward way of getting them to the client in a nice document format, there are some reports with limited configuration, and also an api to extract data, but I’m looking for easy wins. These were versioned manually before being signed-off.<p>Design Document(s) - we produced a design document in MS Word and Google docs (mainly using Google docs for better collaboration features internally, and then Word to publish to the client). There was also some smaller design directly against tasks in our issue tracker - these parts weren’t ever published to the client, though mainly weren’t relevant. These were versioned manually, and only 3 large documents were sent to the client for sign-off.<p>Test Plans - these sat in another tool, called TestRail, which we ended up taking extracts from and “tweaking” to provide to the client as sample test plans.<p>User Documentation - we used MkDocs, which is a wiki generated from git + markdown.<p>One of the challenges was the traceability back to the requirements, as this was all manual, and a good part was in my head.<p>I’ve also evaluated many web-based project management systems, and very few seem to solve documentation meaningfully.
======
chrismcv
Some of the options I’m considering:

1) Moving everything to git, and having MKDocs as the source of all
documentation for the project. I’m not convinced this will work well on the
Requirements phase. Versioning would be done with git tags. And I suspect it
will requirement techie effort to get up the point of being useful, while
alienating our less technical (or more entrenched in MS solutions) staff
members.

2) JIRA + Confluence - seems to integrate the Requirements + Design more
tightly, though not sure about delivery of versioned documents to client.

3) Stick with Word + Sharepoint - which I loath.

