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 5 years ago.
Improve this question
In an answer to the question Documents for a project?, Chris Ballance replied that "User Stories" and a "burndown chart" are the two most useful types of project documentation for a developer.
My question is, do you know of any good example[s], which I can see (for example on the internet, or in a book), of these kinds of documentation?
If possible I'd be happy to see many examples, including:
Small/short/simple examples
Big/long/complicated examples
Famous examples
High-quality examples
I don't find this an easy topic to Google for: I find lots written about it, but fewer demonstrations showing it.
A very good place to start as far as books are concerned is User Stories Applied and Agile Estimation and Planning both by Mike Cohn. This have excellent examples and good starting points for anyone first coming to agile methodologies.
As far as website resources they are few and far between. Probably a good place to actually start would be searching for those keywords on Google Images as many people take photos of their burndown charts and User Stories. This helped me a lot when starting. Here are some samples: Burndown Chart, and User Stories
Please note however while a burndown chart is a simple report that you run on your current story points left in an iteration, User stories are more complex than that and do require a bit of reading to wrap your head around. Start with User Stories Applied book for that.
Hope that helps!
I think for both of these questions, you can do a lot worse than scan over Alistair Cockburn's web site. In particular, he has a great article about burndown charts and some different ways to generate them:
http://alistair.cockburn.us/Earned-value+and+burn+charts
(thoug I echo the earlier poster's recommendation of Mike Cohn's work).
One of the tricks is deciding what kind of documentation is good for YOUR project. Do you have many developers, spread over time and space? You will need bigger, heavier, more detailed stories. Do you have one or two devs working in the same place? You can get away with lighter ones. Has the team worked in the system (if it's legacy) for a long time? Light stories will probably do. Is the team new to the system, or are its business requirements complex? This pushes you in the more-detail direction.
If you're on a "small" project by any of the dozen definitions of small, you may be fine with very light stories. Here's an example, again from Cockburn's site:
http://alistair.cockburn.us/Examples+of+ultra-light+use+cases
A few months ago, we started writing the user documentation at the same time as we are developing features. A technical writer is assigned to each Scrum teams.
Having to write the user documentation while developing helps validating the design. The technical writer also participate in the design of the application.
This is in addition of release burndown and sprint burndown.
Additional documentation is created by the team when they feel it is useful to communicate with the product owner. This became less important as we are learning to write better user stories.
Consider reading Ambler's "Agile Modeling". He makes a very strong case as to why just creating tons of full UMLs is a fairly bad idea, and gives some good examples.
Related
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
Currently I am working on porting a benchmark application to another system. I am working alone, so I am frustrated about which software methodology I really have to use. Please give me some ideas.
I am going to assume you're wondering which Agile approach to use on your project as you tagged your question accordingly.
Agile is mainly about:
Delivering working software continuously and regularly
Aiming at technical excellence and avoiding technical debt
Improving the way we work and retrospecting regularly
I'd say whatever you use, even your very own approach to software development, if you can check those three items from the list, then you're pretty much Agile to me. Some people need strict guidelines and artifacts and that's fine, they help people become Agile but are far from being mandatory despite the dogmas out there.
Here's how I would approach your situation.
Take a step back and try to identify the most important features or abilities of this benchmarking application. By most important, I mean those features that the people using it in the end cannot live without. Once you have a list of those, put them on post-it notes, index cards, trello, jira or whatever tool you want to use.
Split each of those features into full-stack chunks of functionality that are business driven. I'm not talking about technical tasks here, but smaller features usable by actual people. I usually opt for the "Grandma Driven" approach here, asking myself "would grandma be able to understand what I'm trying to do?". It's just to make sure I'm focusing on a full stack feature and not a technical task like "populate database". One way to see this is also by applying dimensional planning to each of the features you identified (http://www.xpday.net/Xpday2007/session/DimensionalPlanning.html).
Set yourself an iteration length (I usually go for 1 or max 2 weeks when I'm working alone) and get to work one small item at a time. Don't write code for later, only what you need to solve the problem at hand. Quality is not an option. Focus on good coding and testing practices.
At the end of your iteration, check how many features you implemented and put that number somewhere on a chart, in a google spreadsheet or whatever. This will help you see if you're on track. Get feedback from colleagues or any potential users of the system and reflect on that feedback. It's not because you're porting to another platform that you can't make it better.
If you end up not having small enough granularity with what's left or not enough stuff in your list of things to do, spend some time repeating steps 1 to 3.
At the end of each iteration, keep tracking how many items you did just to see if you still have a good enough pace. If not, ask yourself why and change something in the way you work or get help. Again, your main focus is to make progress and deliver software that works at the end of each iteration.
It might not answer your question and I know I didn't give you an answer of the type, use kanban, scrum or whatever but I truly believe it's not appropriate in your specific case and would only generate overhead and boredom for you.
Hope that helps anyway, good luck with your project.
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 9 years ago.
Improve this question
I'm responsible of finding a good way to document the software project I'm working on.
What things are important to document? Should documentation of code and design mainly be in the code in the form of comments? Should we put text files or Word documents directly in the source control togetether with code? Should we use a wiki?
Factors to think about include how easy it is for the current team to create the documentation, and how easy it is for other developers to find, correct and extend the documentation later. My experience from many projects is that developers tend to not write documentation because the system for writing it is too complex or developer unfriendly, and that after a few years, new developers can hardly find the little documentation that was written.
I'm interested in what approaches you have used in similar projects. What worked well, what did not work well, and why?
Some key facts about the project:
The platform is C# and .NET.
We use Visual Studio and Team Foundation Server for source control and work item (task) management.
We use Scrum and test-driven development and are inspired by domain-driven design.
The software consists of a collection of web services and two GUI clients.
Other clients are going to integrate with the web services in the future. The integration will be done by other developers on other teams (so the web services form a kind of API).
SharePoint is heavily used throughout the development environment. Most projects have a SharePoint site, including ours.
On our project's SharePoint site we currently have a bunch of MS Office documents on things like requirements, design, presentations for stakeholders etc. Keeping everything up to date is hard.
We also have a SharePoint wiki for the development team only, where we document things in an unstructured manner as we go along. Examples include how our build scripts are organized, our testing policy, coding guidelines.
The software is an in-house application in a fairly big financial institution.
The software is developed by a team of six people over a period of ~1 year.
The developers are consultants hired in for this project only, and will not be available to help in the future (unless the client decides to pay for it).
The client has few guidlines for how this kind of project should be documented.
I think the most important things to document are the decisions. This goes for everything from requirements to architectural choices. What are the requirements of module X? How are these requirements represented in the architecture? Why did you choose architectural pattern A over B? What are the benefits? The same goes for source code: it is common knowledge that commenting the why is way better than the how.
How you document these decisions does not matter that much in my opinion, whether you use a Wiki or a Requirements document made in Word. More important is that these documents are always up-to-date and that it is easy for anyone to access them. This can be achieved by using a wiki, or placing the documents under source control, as you say. If only a few have access to them, they are more likely not to get updated, and not to be read when necessary.
We use a Wiki for our current project and it works very well. It is easy to access for anyone (developers, managers, and customers) and a history can track changes, so you know what has been changed and why. Furthermore, we try to document the code in a meaningful way and document the major design decisions. We try not to document too much, e.g. minor things, as it is always hard to keep those things up-to-date and it is not worth the effort, imho.
Worst for me than lack of documentation is excess of documentation.
Keep in mind that yes: it's really important to document your project, but also that the major part of your documentation is always at risk of never been read at all.
So, I think that a good starting point consist in thinking of your documentation more like something that you may use to introduce new developers to your project than an over detailed description of the inner workings of your software.
G'day,
Definitely use a wiki. I'd recommend TWiki as it's an excellent and extensive implementation of a wiki without being too complicated to install and manage.
Here's a couple of initial thoughts.
Categories:
Start off with an initial ontology of what you want to capture but
allow people to add new categories or sub-categories as required,
allow people to retitle (sub-)categories as required and maybe as agreed for this one so you don't get fragmentation for multiple names for basically the same thing.
let any initial (sub-)categories wither and die if they are left empty. Do this at the end of the project as some areas may only have entries towards the end of a project.
Tagging:
Start using a tag cloud. BTW here's an excellent plug-in available for TWiki to start classifying content early on in the project. Retrofitting tags is almost impossible to do. Starting tagging early also allows people to search for information that may be there already rather than having the same info located in multiple places.
HTH I'll come back and add more points as I think of them.
First and most important, have the comments written in such a way that NDoc can parse them. This is the best way to have the code itself documented, as the developers have to change their development practices very little, and you can generate pages that explain the code without having to look at the code.
Second, getting developers to write documentation is not easy, and getting them to do it might be an exercise in futility. This is where products like Fogbugz come into play. They will help manage the development with tickets, help track check ins, and when your done an iteration, generate release notes.
In conclusion, your best bet is to find the most effective solution that fits in with the devs existing process. If it impacts their development process very little, they will be more likely to adopt the system.
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 12 years ago.
Improve this question
Please feel free to move this to meta/superuser if this is the wrong place. But this is a developer related question.
I have a smallish company with about 10 employees (developers). Often when I am browsing the internet, I come across various techniques and methods which I would like to share with them. Now one way is to simply point them to those links, but that's not too effective as sometimes the link dies, our connectivity is down, people may want to add some comments/thoughts etc.
I am wondering what is the best way to organize all this data. Couple of questions:
Should I use a SO clone? Wiki? Digg clone?
Personally I dont want to use a wiki. I find it to be a pain to create links manually. I just want to post stuff and links and select an appropriate category and people can then view and comment etc.
How to get everyone involved in this process? SO does it well by giving points to users.
How does your company manage information?
Thank you for your time.
I quite liked a process once upon a time.
Start a knowledge base within the company using Blog/Wiki/SharePoint. SharePoint is nice in the fact that it is basically setup and go. You can modify to specific needs down the line. With this you should allow your staff to add posts or blog entries etc, and then once a week/month/whenever you should have a half day "learning" session.
In this session everyone can share idea's and "nice-finds" and then share with their fellow staff; alternatively, you give each member of the team the opportunity to "teach" a session whereby they can share a technology they've found and basically pitch it to the team.
This gives the following:
Adds to teamwork
Gives opportunities to change the way they work, by introducing new technologies
Active learning is always better than passive
The problem comes with people who are introverted, non-confident or simply do not have the time to give lessons, all of which can be overcome by lowering load, allow some to do written presentations, etc.
Hope this helps.
Use a wiki or a blog. Preferably one with both. That way they can search for things and you encourage them to post their own information. Its not easy to get everyone on board but keep trying.
I find the best way to get people involved is by example. Post good stuff and not just 'stuff I found to day about blah....' I read pages out there that all do it link to some new announcement or another - waste of time I think. Better to post somethings of relevance, but not just links. Put some comments along with links.
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 3 years ago.
Improve this question
We have a project hand over from on shore team to our team (off shore) not long ago. However we were having difficulties for the hand-over process.
We couldn't think of any questions to ask during their design walk-through, because we were overwhelmed by the sheer amount of information. We wanted to ask, but we didn't know what to ask. Since they got no question from us, the management think that the hand-over process was been done successfully.
We had tried to go through all the documentation from our company wiki page before attending the handover presentation, but there are too many documents, we don't even know where to start with.
I wonder, are there any rules or best practices that we can follow, to ensure a successful project hand-over, either from us, or to us.
Thanks.
In terms of reading the documentation, personally I'd go for this order:
Get a short overview of the basic function of the application - what is it meant to achieve. The business case is probably the best document which will already exist.
Then the functional specification. At this point you're not trying to understand any sort of how or technology, just what the app is meant to do. If it's massive, ask them what they key business processes are and focus on those.
Then the high level technical overview. This should include an architecture diagram, required platforms, versions, config and so on. List any questions you have.
Then skim any other useful looking technical documents - certainly a FAQ if there is one, test scripts can be good too as they outline detailed "how to" type scenarios. Maybe it's just me but I find reading technical documents before I've seen the system a waste - it's too academic and they're normally shockingly written. It's certainly an area I'd limit the time I spent on if I didn't feel I was getting a reasonable return for the time I was spending.
If there are several of you arrage structured reviews between you and discuss the documents you've read, making sure you've got what you need to out of it. If the system is big then each take an area and present to the others on it - give yourselves a reason to learn as much as possible and knowing you're going to be quizzed is a good motivator. Make a list of questions where you don't understand something. Having structured reviews between you will focus your minds and make it more of an interactive task, rather than just trawling through page after page of tedious document.
Once you get face to face with them:
Start with a full system demo. Ask questions as they come up, don't let them fob you off with unclear answers - if they can't answer something have it written down and task them with getting the answer.
Now get the code checked out and running on your machines. Do this on at least two machines - one they lead, one you lead. Document the whole process - this is the most important step. If you can't get the code running you're screwed.
Go through the build process. Ensure that you can build the app (including any automated build and unit tests they may have). Note that all unit tests should pass - if they don't or if they say "oh, that one always fails" then they need to fix that before final acceptance.
Go through the install process. Do this at least twice, one they lead, once you lead. Make sure that it's documented.
Now come up with a set of common business functions carried out with the application. Use this to walk the code with them. The code base will be too big to cover the whole thing but make sure you cover a representative sample.
If there is a database or an API do a similar exercise. Come up with some standard data you might need to extract or some basic tasks you might need to carry out using the API and spend some time working through these with them.
Ask them if there's anything they think you should know.
Make sure that any questions you've written down anywhere else are answered.
You may consider it worth going through the bug list (open and closed) - start with the high priority ones and talk through anything particularly worrying looking. Even if they've fixed it it may point at a bit of code which is troublesome.
And finally if the opportunity exists - if there are any outstanding bugs or changes, see if you can pair program a couple.
Do not finally accept the app unless you are 100% sure you can:
Get the code to compile
Get the code to build (including the database)
Get the application installed
Do not accept handover is complete until they have:
Documented anything you picked up on that wasn't covered to your satisfaction
Answered ALL of your questions - a question they won't answer after being asked repeatedly screams of something they're hiding
And grab their e-mail addresses and phone numbers. Even if it's only informal they'll probably be willing to help out if the shit really hits the fan...
Good luck.
My basic process for receiving a handover would be:
Get a general overview of the app, document it
Get a list of all future work that the client expects
... all known issues
... any implementation specifics
As much up-to-date documentation they have
If possible, have them write some tests for critical components of the system (or at least get them thoroughly documented)
If there is too much documentation (possible) just confirm that it is all up to date, and make sure you find out from them where to start, if it is not clear.
Ask as many question as possible; anything that comes to mind, because you may not have the chance again.
Most handovers, perhaps all of them, will cause a lot of information to be lost. The only effective way to perform a handover that I have seen is to do it gradually. One way to do it is to allow a few key people from phase One to stay on the project well into Phase Two.
The extreme solution is to get rid of all handovers, and start using an Agile mindset.
As a start, define the exit criteria for the handover. This should be discussed, negotiated and agreed with both parties and make sure higher management knows this. Then write up a checklist of all things needed to achieve the exit criteria and chase it.
Check out "Software Requirements" and Software Requirement Patterns for ideas on questions to ask when gathering information about a project. I think that just as they would work for new development, they would also help you to come to terms with an existing project.
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 4 years ago.
Improve this question
What would you suggest for the following scenario:
A dozen of developers need to build and design a complex system. This design needs to be documented for future developers and the design decisions must be noted. These reports need to be made about every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about the things they helped design and integrate and then one person combines each of these documents together. The final document will probably be incoherent or redundant at times since the person tasked of assembling everything won't have much time to adjust every part.
Assume that the documentation parts from each developer arrive just a few days before deadline. A collaborative system (i.e. wiki) wouldn’t work properly since there wouldn’t be anything to read until a few days before deadline.
Or should a few people (2-3) be tasked with writing the documentation while the rest of the team works on actually developing the system? The developers would need a way to transfer their design choices and conclusions to the technical writers. How could this be done efficiently?
We approach this from 2 sides, using a RUP style approach. In the first case, you'll have a domain expert who is responsible for roughing out the design of what you're going to deliver - with developers chipping in as necessary. In the second case, we use a technical author - they document the application, so they should have a good idea of how it hangs together, and you involve them right through the design and development process. In this case, they can help to polish the design, and to make sure that it matches what they thought was being developed.
We use confluence (atlassian's wiki-like-thing) and document all kinds of different "things". The developers do it continiously, and we push each other for docs - we let peer pressure decide what is necessary. Whenever someone new comes along he/she is tasked with reading through everything and to find out what still is correct. The incorrect stuff is either deleted or updated as a consequence of this. We're happy when we can delete stuff ;)
The nice thing about this process is that the relevant stuff stays and the irrelevant stuff is deleted. We always "got away" from the more formalized demands by claiming that we could always construct the word documents they wanted if "they" needed them. "They" never needed them.
I think alternative 2 is the less agile, because it means a new stage to the project (although it may be in parallel with tests).
If you are in an agile model, then just add documentation (following a guideline) as a story.
If you are in a staged approach, then I would nevertheless ask developers to work on documentation, following some guidelines, and review that documentation along the design and the code. Eventually, you may have a technical writer reviewing everything for proper English, but that would be a kind of "release" activity.
I think you can use Sand Castle to document your project.
Check it out
Sand Castle from Microsoft
It's not a complete documentation, but making sure that interfaces etc. are commented using Doxygen-style comments means writing code and documenting it are closer together.
That way, developers should document what they do. I still think a review by the architect(s) is needed to ensure consistent quality, but ensuring people document what they do is the best way to ensure they follow the architecture.