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

Posted by tmaly on Thursday July 23, 2015 @10:58AM
from the ask-hn dept.

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.

( 10 comments | 20 points | on HN )

Re:Ask HN: What is a good system for program specs? by arrty88 on Thursday July 23, 2015 @12:12PM (#9936667)

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.

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by imglorp on Thursday July 23, 2015 @12:49PM (#9936921)

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.

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by vaceletm on Thursday July 23, 2015 @12:15PM (#9936690)

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

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by marekr on Thursday July 23, 2015 @11:25AM (#9936310)

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

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by rimunroe on Thursday July 23, 2015 @12:03PM (#9936606)

Requirement #2 was "open source"

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by stephengillie on Thursday July 23, 2015 @12:16PM (#9936701)

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.

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by PaulHoule on Thursday July 23, 2015 @12:47PM (#9936909)

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.

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by dhimes on Thursday July 23, 2015 @11:58AM (#9936570)

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.

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by e19293001 on Thursday July 23, 2015 @10:20PM (#9939790)

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).

[ Parent | on HN ]

Re:Ask HN: What is a good system for program specs? by tmaly on Thursday July 23, 2015 @01:37PM (#9937264)

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

[ Parent | on HN ]