Ask HN: What is a good system for program specs? | Hacker News Reader

Ask HN: What is a good system for program specs?

20 pointstmaly10 comments

I am looking for a system that I can use to manage and collaboratively edit programming specifications and requirement docs. 1. web based 2. open source 3. Have basic access control 4. Show history / changes of a document 5. Be easy to use for non-technical people ( not command line git) 6. export to popular formats such as docx and pdf 7. have a basic search feature where I could look by keyword of changed docs by a date range or all doc versions as of a specific date.

View on HN

Used Wikimedia for all of our tech docs, design docs, etc. Super easy to look up all of the product changes coming down from the business and the reasons for them years later.

We're using Confluence for that. It's nice because issues and branches are all cross linkable with wiki pages. I suspect you could get similar behavior in wikimedia with other trackers and hubs.

Usually programming docs are documents but it's far from being the only possible representation.

I would suggest to look at Tuleap Trackers[1]. The tracking system is flexible enough to allow you to define your own layout for requirements and define a set of elements to help you categorize them.

I'm from the development team and we are using it for our very own requirement tracker (in an Agile way but that's not mandatory to follow an agile methodology to use it). You can have a look at some of your requirements / user stories:

* https://tuleap.net/plugins/tracker/?aid=7923 you can see how to structure the text and at the bottom the discussion and the modifications done by each user. * https://tuleap.net/plugins/tracker/?aid=8262 same with another topic.

[1] https://www.tuleap.org/about-tuleap/features/tracking

Just by reading your list of requirements.. Google Docs?

Requirement #2 was "open source"

I was going to suggest both TFS and Sharepoint Online, except for requirements #1 and #2. I've set up good documentation repositories with both. Sadly they don't integrate well with Jira, but I've heard good things about Confluence.

If you really want control, do it by using something like an issue tracking or case management system.

The most important character of "an issue" or "a requirement" it is that it is a unit of work that can be "done", "in progress", or "not done". Throughout the life of the project, there are going to be negotiations between people about what exactly is done and how requirements will change, and those kind of systems are designed for that and capture not only the changes but also some of the semantics.

Some issue tracker may have (6) AND (7) built in. Otherwise you may need to make some reports.

Maybe Redmine's wiki feature would work for you. As a bonus, it integrates with your VCS and has issue tracking so your PM and source control are all viewable in one place.

Emacs org-mode could be a choice though it takes some ( or long) time to learn. You document in plain text and may export to tex, pdf, html (docx is not supported AFAIK).

is Confluence available as source? a wiki might work, I would just need a good way to convert from the wiki format to docx,pdf

Reply on news.ycombinator.com