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.
Related
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 is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
During the development cycle of a feature, the feature is constantly changing, even after the point where the it meets all requirements (UI improvements, etc...). If you have automated tests for that feature, these changes can break your automation and you will have to rework it. If the feature keeps changing though, it does not make sense to rework automation after every revision. At some point, however, you have to automate it so you can do regression testing. How can we find the optimal time to rework automation? How do we get the optimal amount? My team agreed that we over-reworked the automation of one of our features. One example of a mistake we made was to rework automation right before a conference where we showed the feature off to customers to get customer feedback. We should have known that customer feedback would result in more changes to the feature. Functional testing should have been enough in that case.
Does anyone have any tips or experiences to share?
The general tip would be to come to a consensus on what "done" means for the feature before you you start building it.
If during the build you come across some new tweaks that you'd like to add to improve the feature (or whatever) don't add them to the existing story - write a new one... and make sure that you prioritise it against the other things that you need to be doing.
This is also sometimes, but not always, a sign that you're working with increments of functionality that are too large. Try splitting and thinning the stories further until you can write down some quite concrete definitions of "done" for the feature. Consider automating those tests of "done" before you start building (but don't go overboard).
You might find the Specification By Example book of use.
According to my experience is that the feature you've been developing is not understood by the customers yet, fully.
Separate the feature into small parts like #adrianh suggested.
One more tip for the instable customers: Let them first see the pseudo prototype at first hand, even maybe in the planning meeting (code it directly to html or something easier something like a prototyping/diagramming tool). Let them play with it. This way, you will have an easier time with your features.
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 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...)