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.
Related
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
Does anyone out there have any experience with Jitbit Helpdesk? My comapny is looking to replace our current Ticketing system due to costs. We have run the basic company searches such as DNB, without much luck (guessing due to the size of the developer's company).
We plan on using the system with approximately 100 users, and have a dedicated IT department to support and modify the code to fit our needs.
My company is willing to go with a smaller provider (we will be self hosting) but have been trying to find companies of our size or larger that use this software to get their take on it, both good and bad.
If you have experience with this ticketing system I would appreciate your feedback, both good and bad.
My company would prefer to do a reference call, but even some good honest feedback from the users at Stack Overflow could turn the tide one way or the other.
My alternative would be to start Googling JitBit, find companies using the hosted version, then trying to call their IT departments until I find someone that could possibly share their experiences, (That sounds absolutely horrible to even attempt, but I'm fighting a large compliance and purchasing department).
Thanks everyone!
If anyone else comes into this thread with the same question, I just wanted to check back and let you all know how it went.
We did purchase the Jitbit software, and after some code modifications (we purchased the license with source code) it works extremely well.
Some caveats:
The system is more geared towards helpdesks that accept external callers versus an internal corporate helpdesk, and there are no group based permissions they are all handled on a user basis. I had to write the group security by co-opting their department assignments and writing some custom permission code, but for the price(~2k/year versus 100k/year), we are extremely happy with it.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
Gathering requirements is an essential stage creating software or web applications.
I have searched the web extensively without finding any directions on how to elicit requirements for personal projects. All information i found - including books i read - is focussing on different stakeholders.
So i´m wondering, what would be the best way to 'gather' the requirements for personal projects?
I can't imagine i'm the only one with this question. I have plenty of ideas for webapplications. Since i am the only stakeholder at this time - no users are identified yet, i need to develop a couple of applications for personal use - i find it hard to interview my self to elicit those requirements.
As English is not my native language, apologies for possible textual errors.
You can have a document with all the information you have in your head of the project in a bullet list format called "Project Memoir". Just list all the information & business rules you need to put in the project. You can after that start developing a kind of informal Software
requirements document (as it's for a personal project) containing some essential information for you in the development phase, like a feature list with their description, use cases & scenarios that will help you in testing in later phase, mock up screens for defining the UI look & elements, data elements lists for defining screen contents. Just keep it simple & easy as it's for only your personal use.
Hope that would help :)
The questions are supposed to be a trigger of a thought process.
What makes it any different in case you are the developer next to the stakeholder? Your thoughts are those of a stakeholder and you will have to try to identify your own requirements by this process.
Identifying your own requirements with a structured approach will help you identifying requirements that you would otherwise have encountered during development.
If the sole purpose is not only personal, I doubt whether it is a good idea to start developing. Then you will need to find prospects to interview. Investigate the possible markets.
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 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
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...)