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...)
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
This question does not appear to be about programming within the scope defined in the help center.
Closed 5 years ago.
Improve this question
It sounds strange, but that's what I need. An effective way to document a Scrum project.
I agree that it's a waste of time to produce User Stories and a Requirements Documents.
But sometimes we need to have the vision of how the software currently works.
How do you do that? Do you know some best practices or case scenarios on this?
Thanks
The short answer is this: you can write anything you want or need to about any project, Scrum or otherwise. Scrum doesn't tell you how to document, but it doesn't tell you not to. The way you document is in itself irrelevant to Scrum.
That said, if you need to understand how the software currently works, a document will not help you. Documentation often lies. If you're trying to understand how the system works, a document will only tell you what people think or want to believe is the truth.
What you should consider, is to use executable specifications and Test Driven Development to prove that what you believe the software does is actually true. automated tests combine documentation, examples and regression tests all into one offer.
There are several kinds of documentation that can help you. It depends on your context which ones you need, and at what detail level. You could also use a tool such as MOOSE to create project specific visualizations of your software at all levels. Some simple documents are:
A story map
Gherkin style high-level features and scenarios
If you've tracked your product backlog items through completion, including acceptance criteria for each you should be able to point to the list of completed product backlog items as documentation. Everything you've programmed should be associated with a PBI, so the completed PBI's document your project.
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 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 4 years ago.
Improve this question
I'm working on an app to provide an easy way for people to track the status of a bill [and various other political information]. I love the idea of OpenCongress, for instance, which surfaces summary information on legislation as it navigates the political process, but I'd like it if it had a tag-based search system and some other rich search options, as well as more conveniently accessible voting history and term information. And while they now have JavaScript widgets which show the current status of bills you select, I think more could be done in this regard.
I don't know where they get their data, though, and while they have an API of their own, I don't know whether sticking a wart onto it is the best way of implementing what I envision. For all its touting of transparency, it's not at all obvious to me what data the government makes available, or even how to find that out!
So, does anyone know any good APIs for obtaining information on the status of American legislation, legislators (such as voting histories), agencies and/or upcoming elections? (Or, if you think it's really interesting, feel free to post any other APIs that are relevant to U.S. politics.)
Although they aren't APIs, www.data.gov provides official data sets, which can be mined. For now, I think this is the closest you're going to get to an official, centralized source of data.
Check out ProgrammableWeb's list of government-related APIs. Not all of them are the US federal government, so you might need to sift through it a bit. Also, they're not all provided directly by the government.
There's also an open source project that provides an API for thomas.loc.gov.
We publish feeds of all legislative information for the New York State Senate, with an API, at: http://open.nysenate.gov/legislation/developers
I'm not sure if it addresses exactly your concerns but the Watchdog site tries to do something like this. Their source is available online and they extract a lot of information from public records. A lot of the published stuff is in rather antiquated formats (huge zipped XML files) and so the whole process is not totally straightforward.
You should check out the collection civic APIs that are listed here:
https://live.temboo.com/library/keyword/civic/
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 looking for a good in depth documentation/how-to for DataContractSerializer. Google turns up a number of related articles but nothing jumped out at me. (I'm not looking for the MSDN link)
A little clarification: I have never use serialization in .NET but have a working app that does that I need to update/modify. I have a fairly good Idea how I would do what I need to do if I had designed the serialization system but I'd rather not hunt trough a pile of MSDN class documentation looking for how they expect me to do it. The MSDN stuff works well for figuring out how something works (as does Google because at that point you have a specific term to Google) What I would like is a well done "here is how it works and this is all the details" document targeted at showing me how to fit the pieces together rather than figuring out how they work. I'm afraid what I'm looking for is a bit of an "I'll know it when I see it" thing, and I have never had good luck Googeling for that sort of thing.
I'm particularly interested in specific pages that people have used and personally found very useful. If you are thinking of something particular right now (before going to Google) that is what I'm looking for. If not...
Try this MSDN link instead, http://msdn.microsoft.com/en-us/library/ms733127.aspx
but I'd rather not hunt trough a pile
of MSDN class documentation looking
for how they expect me to do it.
It's Microsoft, what do you expect??? You ARE expected to use it the way they want it. :)
This article is very helpful because it shows the benefits of DataContractSerializer in contrast to XmlSerializer. This was the first article I used when learning about WCF and DataContractSerializer.
Not to be disparaging but isn't a Google search the best way to get this kind of information? The most helpful and informative links will be on the first page as those will be the most linked and visited.