Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
At the moment I am using Visual Source Safe (yeah yeah!) to store my Technical Specification documentation.
The actual docs are written in MS word.
If find that having the spec written in word format to be a big burden, for specs to be truly used there shouldn't be any barrier to usage and more importantly access.
If I can't quickly scan a document, hyperlink to other dependant documents or sections, what use is all this anyway?
So with that as a background:
what software exists to create truly accessable documentation? i.e. hyperlinks to other pages/sections etc? Or even queryable so I can view all documents that are dependant on module 4.5.3
Is it basically just a Wiki? Anything else?
Wikis are great for creating and maintaining specs. However, it is difficult to generate a big ol' paper document that makes a satisfying "thud" when you drop it on peoples' desks.
I've gotten by with Word. Just learn to take advantage of all the automation it has for cross-referencing, indexes, tables, pagination, etc.
I think of specs as having two audiences: decision-makers and developers. The Word documents are for the decision makers. The developers will come up with something useful later when it is time to implement the specs.
I believe Word supports the idea of sub-documents (links to other documents), however I'm not sure how well it works without VSS, much less with VSS. But it's something to look into.
A wiki is, however, pretty much what you are looking for.
Java has API docs generated by javadoc, Python has API docs generated by tools like epydoc.
What language are you working in? Have you looked for tools like javadoc or epydoc for your language?
We just started using Confluence for technical docs and notes: http://www.atlassian.com/software/confluence/
It's a full-featured browser-based wiki that just works out-of-the-box, though you can tweak it to your heart's content. It features everything you'd expect from a professional wiki, including security, rich text, hyperlinks, and attachemts; and it's intuitive enough that even our non-technical people (with 3-letter titles starting with 'C') use it.
If you visit Atlassian's web site (see link above), you can play with their online demo ... and they eat their own dogfood to provide community support.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
Can anyone give advice, or point to any guides, on how to manage a community of open source software developers in writing api documentation?
A typical, unmanaged, starting point for most projects is to have a project wiki where anyone can freely create pages, add content to existing pages, edit existing content etc. The problem is that, despite people's best intentions, the wiki can easily end up being a disorganised, poorly written, incomplete, written in disparate voices etc etc.
So, what to do to improve the quality of the documentation?
I suspect a key ingredient is clear editorial/style guidelines, something similar to http://en.wikipedia.org/wiki/Wikipedia:Encyclopedic_style#Information_style_and_tone. Can anyone point to an example of such a guide tailored specifically to software apis?
Are there any other practices that people have found useful? E.g. form a core team of editors and accept that most documentation that gets added by the community will most likely need to be 'strongly edited'?
The short answer, that the solution is social/human and not technical. The way to get good documentation for any project is to have someone with time, in charge of doing high level organization for the documentation, and then being involved in the development and user communities to ensure that the documentation remains up to date and continues to address the problems and confusions that users typically have.
Community projects have accepted that you need point people (i.e. "managers," for aspects of the project like "translation," and "release," and for various components. The same thing needs to happen for documentation.
As for tools, Sphinx is really great though it's not "wiki like," exactly you can use whatever version control system your project is comfortable with to store documentation and configure your web server to rebuild the documentation following commits/updates/pushes. Which has always worked just fine for any project I've worked on/with.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 6 years ago.
Improve this question
I wish to learn Gherkin so I can use it with specflow; I am looking for a document I can read on the train e.g. print out on paper.
All I can find on the web is short disconnected descriptions that don’t tell a story and require lots of clicking between web pages to read.
(I don't mind buying a good if it has lots of good Gherkin content in it)
The RSpec book is a great book to introduce some of the concepts of BDD, Rspec(as a .net dev you should check out MSpec) and Cucumber which is a based on Gherkin.
The best free printable resource is the awesome cuke4ninja which has a PRINTABLE pdf (follow instructions in README.md on github to create).
There is a BNF definition https://github.com/aslakhellesoy/gherkin/wiki/BNF if you are that way inclined.
There's a Cucumber book out now too
EDIT: It looks cuke4ninja.com isn't what it was anymore (it's now some dating site) but the site is still kept on github. The link above has been changed.
I've used Writing Features - Gherkin Language as the recommended introduction for newcomers at work, and it has worked out really good
I would start with the official Gherkin Language Page and work your way from there. It is a broad enough overview to get the major components and show people that it's really just a human-readable, business language for getting requirements down.
From there I would expand to the The Official Cucumber Tutorials or checkout this blog post for more insight.
If you're looking for something to hold, you should pick up The RSpec Book which covers Gherkin and Cucumber; the language is so terse that it can be quickly covered and learned, so you're unlikely to find a book dedicated to just Gherkin.
This is a guide I've put together from a few years of working with Cucumber and Gherkin
https://docs.google.com/document/d/1pkhePZ7eaOWskai3gmopa4Sp6o88r1kGZITVRs_PN7Q/pub
If you're looking for something that is offline I cannot recommend The RSpec Book (http://www.pragprog.com/titles/achbd/the-rspec-book) enough. It's a great book and introduces not only BDD, but also Cucumber and Gherkin.
On how to write great Gherkin I have found this article very useful: http://www.engineyard.com/blog/2009/15-expert-tips-for-using-cucumber/
Good luck
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm currently developing the front end of a new CMS for a digital streaming company, the main problem the project has is keeping track of the technical language that has sprung up around it.
It currently involves around 60 staff in four countries, aside from a wiki (which has thus far failed to be kept up-to-date), anyone have any good tools or tips for building and maintaining a glossary for a project like this?
aside from a wiki (which has thus far failed to be kept up-to-date)
This comment makes me pretty nervous about suggesting other solutions. Wiki's can come with their own problems, but keeping it up to date is not a problem inherent in the platform. It's a cultural or organizational problem. A wiki provides a very easy way to track and update data. If, today, you cannot keep it up to date, ask yourself how you will solve this problem if you change the tool?
Changing to another platform could solve things like: The wiki isn't scalable for that amount of data; we want to make controlled edits; we need to release in multiple languages; we need to release in other formats.
For the updating problem, try something simple to start, like assigning a dedicated team member to glossary maintenance. They don't have to be the only contributor, but if you have someone who is dedicated to paying some attention to this area you will have a much better chance of keeping things up to date.
In an untended garden, it's not the fault of the soil that you have no flowers.
DITA has a glossary specialization. You can maintain a central company glossary in it. In individual company documents, you create a mini glossary topic then use a content reference to pull any terms you need into your document.
It does sound more like a version control issue though.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
What tools exist for developing platform indepedent API Documentation?
I'm in the process of designing a proposed API, and want to write documentation in a structured and easily editable way. A lot of the answers I've seen have basically been "Use built in language specific documentation tools", but since I'm designing the API from a 'top-level', rather than implementing it, this isn't so useful. I'm looking for a CMS for API Documentation
I've seen a few suggestions to use PBWiki or Confluence, but I'm not convinced that a plain wiki is the best option, though the version control aspects are nice.
In theory, a Drupal build with CCK for API calls and Views for reading the API, but that's a bit of heavy lifting for what I'm looking for.
Is there a API Documentation Management System out there? What are the best options for writing and managing platform-independent documentation for APIs?
I've seen the related questions for this, but there has yet to be a satisfactory answer.
Any structured text language will do. I'd use latex, and troff is old school.
But you may have missed the point of the suggestion to use doxygen or whatever. If you do that, then writing the documentation is also laying down the scaffold for the eventual implementation. Better still, the example documentation will be in the same format as the eventual real documentation and, you will--of course---use source control on it, won't you? So you'll have a potted history of changes to the spec.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
Perhaps if I make the my documentation better I could spend less time supporting developers and more time developing myself:
I develop a critical platform used by 10 other developers and 50 end users. The developers are of mixed ability ranging from domain-experts to relative beginners. Since I'm one of the people who know how the core platform works support requests from other developers usually go via me.
Our documentation is the usual sort of descriptive stuff any mature project will have: We have a large wiki containing details of all the usual operating procedures plus extensive API documentation.
Unfortunately it does not cater well for "how do I fix " type questions:
Would it be possible to make some interactive fault diagnostic documentation that puts users through a standardized fault-finding routine. The documentation would ask users a series of questions, and depending on the user's input would tell them what to do... it would be a very simple expert system, or possibly a documentation state-machine.
The idea would be to help newbies think more methodically about diagnosing faults in this complex system.
My question:
Are there any free tools intended to implement this kind of user-experience? I'd rather not hand-roll this. There must be some kind of framework for interactive help & documentation.
Has anybody implemented this kind of system before?
If you just wanted to have a flowchart/stat-machine thing where the user moves from the start point to a set of possible solutions by answering questions, then you could probably implement this as a set of wiki pages, where the possible responses to questions on one page are links to other pages.
This solution relies on being able to represent the answers to questions as links, which isn't going to work if the information is more form-like. For example, suppose one question is "What brand of graphics card do you have?" where the answer is one of 300 possible options. In this case it's going to be tiresome to create the links :)
If the developers are asking too many questions then I would suggest making them research the question themselves and come up with an answer, then double-check with you instead of encouraging them to ask you every time. It's much easier to ask somebody else than to find the answer yourself, but they're never going to learn if they don't look for themselves.
If the users are asking a lot of questions then you may need some user interface improvements. Try putting hints in the application itself at the top or bottom of the screen maybe.
For both groups of users a wiki can help.
a FAQ in your wiki
if an error happens too often, try preventing it or output a more useful error message (like "if this happens, the likely cause is that...)