Related
Scenario:
20 development teams
each team responsible for multiple microservices
microservice ownership is fluid; teams might trade microservices, teams might drop or add microservices
team identification is important for tools and organization
The teams cannot be named by the feature they are working on, because it will be multiple features, and feature needs change. Naming teams by numbers or letters doesn't feel correct, because it implies order or sequence.
How does one name the teams? If you were a developer on one of these teams, how would you want your team identified?
You can't have names that are both meaningful and meaningless - i.e. they help identify something organizationally but will still make sense when the organization changes.
I recommend meaningless: animals, astronomical objects, or other vague code words. That way you can record them on lists as needed but people can also use them to form mental associations. Think of what "Amazon" and "NewEgg" mean even though they don't actually mean those things.
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
I have been working for a while now but because of my earlier habits i never worked systematically.
I have never created a workflow chart for my software as how the software will work and instead of that i started working directly which in turn leads to many problems later.
Below is a small situation i currently need help with:-
NOTE:I have already created a software which does the following and i don't need any code for it, i just want to know how a workflow chart is created for such a situation.
1) Party List : This is where i would like to store all of the information of my customer.
2) Sales : Here i will sell my products to the customer.
There are 2 cases here, whenever the customer arrives we have an option to
either save it in the party list and select it from the list in the sales form
or type it manually and then save it
Now comes the checking part:-
If an entry was saved in Sales when the checkbox was ticked and the user selected a party, lets say "Akhmed" has been saved AND the user tries to delete the record of "Akhmed" from the Party List form then the software shouldn't allow it to do so as the entry of "Akhmed" already exist in Sales.
Can anyone show me how a workflow chart is created for such a situation?
EDIT
Here is a sample workflow i have made after reading some articles, please point out any improvements that can be made to it or is it completely wrong or anything.
First of all, great question. I wish all software engineers thought first before jumping to writing a code. Especially when it's about anything more serious than a couple of lines for fun.
I think your software flow can be expressed as Activity diagram. An example of activity diagram is expressed on this picture: https://www.tutorialspoint.com/uml/images/uml_activity_diagram.jpg
Basically, activity diagram is a combination of steps and transitions (arrows) connecting them. Step can be just something that happens in the flow, or it can be a logical operator (decision) which branches the flow execution into different directions.
If you need to also emphasize who needs to execute the step, besides just showing what the steps are, you can add swimlanes (horizontal or vertical columns showing the actor names) to the activity diagram. That's where it turns into a Flow Chart diagram. e.g. on this image you can see horizontal swimplanes explaining who does the step execution http://static1.creately.com/blog/wp-content/uploads/2011/11/Support-Process-Flowchart-Template-1024x613.png
Note that terminology can differ from person to person, but these are the names for these 2 kinds of diagrams I have mostly heard and used myself.
There are other kinds of diagrams too, but I think your specific case will be covered with the ones mentioned above. Although... use case diagram can be something you may be interested in, but that does not depict steps. That only will mention actors and what kind of actions they can do with your system. e.g. https://sourcemaking.com/files/sm/images/uml/img_32.jpg
You didn't ask for tools, but I usually prefer to use tools that are rigor (rather than loose like Visio), so I would recommend to use WhiteStarUML. It's free and does a great job. But as I said, it's strictly UML-based, so will require some familiarity with UML.
Finally, about your attached picture:
What you showed looks like an activity diagram with some illegal components on it (illegal from UML specification standpoint). Is it good or bad? - depends. If it's supposed to be a rigor UML diagram then it's bad. If it's just a sketch of an idea - not bad.
Your diagram mentions database sign (called "DB") and arrows connecting to it. That's illegal on an activity diagram UML. Instead, you can have a step which says "Data gets saved to Database", and remove the "DB". Also, you have a single step which says both "Party" and "Sales" on it - that's not a legal UML. I think you tried to express that there are 2 flows. In that case, just have 2 different activity diagrams instead of one.
Your question is quite broad but I'll give it a shot.
I think you want to reconsider your approach. I would suggest reading up on UML sequence diagrams. They are a kind of diagram that provides a way to represent how requests are made within code. UML, in general, can also be used to make class diagrams and other useful flow-like charts for representing code. Many tools, such as visual-paradigm, allow you to build UML diagrams (ex. class diagrams)that can be converted directly into code. This can be useful when getting you started on the program. There is a learning curve with using these tools as different kinds of arrows mean different things, but they can be very powerful. they can also be used to take existing code and convert it to a diagram, which is great when trying to explain how your program works.
here are some other links that might be useful:
lucidchart has an example of a pop-up window diagram like the one you described.
draw.io just allows for you to make the diagrams, not convert them to code, but it is an easy to use tool and integrates with google drive and git hub.
stackoverflow has some info on UML too.
If you are looking for a "professional workflow diagram" UML if a fine way to go, there are many ways they can be laid out and they can be quite professional, I learned about them in school and have used them at work to help plan out the flow of data through our system. There are many more UML tools out there, it might be worth looking into a tutorial to find what's best for you.
You seem to be on the right track, I have never added a database to my flow-charts but it is up to you on how detailed you want to get. You seem to be using the correct symbols!
Here is an awesome, free website that I use. https://www.draw.io/ it was created for making flow charts and other things.
I personally would remove the UI at the beginning of your chart. Try to stay away from the overly technical examples when starting out with flow-charts, hit up YouTube or Google images for some simple, but correct examples.
Good luck friend!
I'm starting a new software proyect and I wanted to use trac to manage it. Mostly because I love it's wiki and I love the way django use it.
One thing I'd like to avoid is to pollute the development board with bug reports and viceversa. A quick round on google left me bare handed so I'd like to ask if any of you have experience setting up trac with different boards, one for regular planning and other for bug tracking.
Opinions?
It's up to you to organise it and there are several possible ways. In my opinion the best is to define two different ticket type groups (see http://{yourTrac}/admin/ticket/type), one for the plan and the other for bug handling:
plan:
'workpackage' for grouping
'enhancement'
'modification'
'task'
=> insert tickets of type enhancement, modification and task as children to tickets of type workpackage (e.g. using MasterTicketsPlugin)
bug tracking:
'bug'
Then use the Trac query language all over your ticket queries and Trac plugins to separate by ticket type, and insert them separated in your wiki pages and milestone wiki-language descriptions, e.g.:
[[TicketQuery(group=type,format=progress,type=enhancement|modification|task)]]
[[TicketQuery(group=type,format=progress,type=bug)]]
[[BurndownChart(milestone=v1.0,label=Plan,startdate=2014-10-20,enddate=2015-05-25,type=enhancement|modification|task)]]
[[BurndownChart(milestone=v1.0,label=Bugs,startdate=2014-10-20,enddate=2015-05-25,type=bug)]]
[[WorkloadChart(milestone=v1.0,type=enhancement|modification|task)]]>
[[WorkloadChart(milestone=v1.0,type=bug)]]
[[TracJSGanttChart(milestone=v1.0,type=workpackage|enhancement|modification|task)]]
[[TracJSGanttChart(milestone=v1.0,type=workpackage|bug)]]
One approach is to add the bug tickets as child tickets to the appropriate tickets of the plan if they are the result of the development and fall out during the testing period.
If your goal is to keep the list of tickets that represent your development plan for forthcoming release(s) separate from the untidy thicket of tickets that represent issues being encountered by users of the current release, how about using ticket "milestone"? So, "bug" reports would be opened in the "current" milestone, task planning (for potentially multiple future releases) would be associated with non-current milestone(s). I assert this allows for clearer description of items in both the current and the forthcoming release.
Someone opens a ticket complaining about how things work right now. If you decide you should address it for current users, you leave it in the current milestone (though you might reclassify it a "task" or an "enhancement"). If you decide it must wait for another release, you move it into a forthcoming milestone, but can choose to leave it called a "bug", it doesn't have to be reclassified as a "task".
Likewise, when you're testing the unreleased code and find a problem, you can call it a "bug", but in the forthcoming milestone; again, it doesn't have to be a "task" just to be considered part of the development plan.
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
I currently work in a small business (15-20 employees, 5 programmers) where most projects are custom built CMS and a few web applications products.
Since I started working there, I have worked on many projects, but specifications for each project vary a lot. Sometimes we get a little detail, a Word document telling what the client wants, and what we are suggesting (suggested form fields, a short description of display, etc.). Sometimes almost nothing except "do what you think is the best approach for this project/module/request".
My question to you guys, who might work in different kind of businesses, is: How (huge pile of paper? Word docs? Visios?) and what kind of information do you get from your superiors, managers, teamates when starting a project (plenty of analysis, drawings, etc.)? How much detail do you get on this?
Hope my question is clear enough, thank you.
Specs..that's kind of funny...how about never :(.
Seriously a lot of companies assume specs aren't needed, its absolutely unacceptable but this is how it is in a LOT of companies. They assume a one liner and the programmer knows what the program should do, the inputs / outputs and so on.
Unfortunately in my case I have to actually help write the specs..and Im the programmer :(.
I mostly get a lot of verbal direction and I use a voice recorder to record the conversation and transcribe it when I am done. I write my own specs from my customers' words.
Then, as a good consultant should, I take the writeup back to the customer and verify it, and get a signature and build it, and they live happily every after! (no they dont, they change their mind a 100 times)
It can vary depending on what group the work falls under:
Support request - If the change will take a short period of time and is fixing something broken, there is this group. This could be as simple as, "Add Bob to the list of authorized users for that ancient form" where the form is something written years ago and aside from adding and removing users, it isn't touched for fear of breaking things.
Service Advisory Committee request - Items that are up to a few days are in this group as these are kind of like mini-projects as the request may be to create a new form or portal for a group. This could be upgrading some 3rd party software where we have some customizations that make the upgrade not necessarily a simple thing for Operations to do.
Project - In this case there are usually a few Word documents and/or e-mail threads that help nail down requirements in terms of scope, budget, and time. These can take months though there is something to be said for having a prototype to change rather than creating the initial prototype to tell if requirements are really met or not. Course my current project is over a year old, still has a few more months to the timeline and already has a successor coming after it is done,i.e. there is a Phase II to go after Phase I.
Uber project - These merit their own group of documentation and are the million dollar, multiple company projects that usually try to document everything up front rarely works out well here. Thus, there is some adoptioon of agile for these but there are still some growing pains to go through as how we use agile matures. Think installing a dozen modules of some off-the-shelf software that requires both internal and external developers to customize the suite for our specific needs as the software is supposed to be very robust, flexible and help save lots of time and money on how people otherwise do their jobs generally. Think ERP or CRM for a couple of examples here.
We are a 16-person company that creates and supports customized software for small retail shop owners.
The projects we get fall into three general categories (as related to specs):
"Here, automate this form." A sales person explains that our customer only wants this form to appear where they can fill it out and print it to make it look professional to their customer. Our specs is a single piece of paper that looks something like an order form or report. This is always false; they want pop-up lookups, automatic updating from other sources, and "while you're at it" add-ons that more than double the time. These, we've learned to just live in the moment and let the project take its course. By the time we're done, the program doesn't look anything like their original form.
Small changes. Like a simple e-mail explaining that the background color is stale, or a request to sort a report by a different column. These, we just do as time allows.
Big company integrations, where we're tasked with making our software work with some big outfit like Intuit (QuickBook) or FedEx (shipping rates). These often have well thought out documentation and sample code. We get 100's of pages in word documents or pdfs. The problem with these is when their specs are wrong. We find out about inaccuracies when we try to test or certify our integration. In these instances, we usually take longer in certification than we did to originally develop the processes.
In all cases, the real trouble is when a sales person promises a solution to the customer before even asking a programmer what it would take. As recently as 2 weeks ago, a sales person got into real trouble and had to issue a refund (that person is no longer with the company).
None - at least not from management.
Instead, as a developer (and particularly one leading a software project right now), I'm expected to contact my users/customers/etc and work directly with them to come up with our specifications and requirements. The documentation I do request from my team is only what will be useful to the team. I am lucky in that management rarely requests a document that doesn't make sense or won't provide some use to our project.
I currently have a half-dozen or so specs each 60-80 pages. One of them is 80 pages with no table of contents. Good times.
Our Product Managers and senior engineers prepare three planning docs for our data management software projects.
High-level requirements: 1-to-3 sentence descriptions of hardware/software supported or specific feature for this project. (10-15 pages of Excel-like grids)
Technical details: Engineering implementation of each high-level requirements. Up to a page for each, depending on amount of detail. (30-40 pages of filled-in feature details)
Business agreement: Summary of 1 & 2 with engineering schedule and Product Mgmt's market analysis. Everyone signs off on this. (5 pages analysis, 20 technical)
I haven't seen work flows or other Visio-like details in our specs. The prioritized requirements and schedule prove critical, so we understand when to lop things off to save development and testing time.
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 8 years ago.
Improve this question
I work for a CMMI level 5 certified company and one thing I hate about is the amount of documents we prepare (As a programmer I already hate documents). We have lots and lots of documents like PID(project initiation doc), Business requirements, System requirements,tech spec, Code review checklist, issue logs, Defect logs, Configuration management plan, Configuration management check list(s), Release documents and lots...
Almost 90% of these docs are just done for the sake of QA audit :) .. What do you think are the most important documents for a project? What documents can be used in the long run by another developer?
Please share your good practices here. I would like to use them for my own projects or the company I am planning to start in the long run.
Thanks
The key document is a good functional spec. There should be one and only one reference document for a system.
Overdoing documentation proliferates a large number of small requirements and spec documents every time someone changes a system or interface. For a system of any complexity, before long you have your spec distributed around several hundred assorted word, excel, visio and even powerpoint files. When this happens you lose clarity about what is current or even whether you have located and identified all pertinent documentation.
The BRD-SRD-Tech spec progression is based on an assumption that the business signs off the BRD, a business analyst signs off the SRD against requirements documented in the BRD and the technical specification is signed off against the SRD. This generates a web of sign-offs, multiple documents with redundant information and makes it difficult and clumsy to keep the spec documents up to date.
Because of this, subsequent requirements documentatation tends to take the form of a series of change request and supplemental requirement and spec docs, each with their own sign-off and audit process. You gain CYA and audit trail (or at least the appearance of an audit trail), but you lose clarity. There is now no definitive reference document for the system and it is difficult to establish what is current or relevant to any particular activity. The net result is that your business analysis process gets bogged down in forensic research, which adds overheads and latency to delivery schedules.
A spec document should be built in such a way that there is one definitive reference for any given system or subsystem. The document should be kept up to date and versioned. Get a good technical documentation tool like Framemaker, so your process can scale, and the document has some structural integrity of the sort lacking on Word.
For me the only real document I ever use is a spec. The more detail the better. However it doesnt need to be all completed at one time, and it doesnt need to be particularly formal. What is far more useful to me than documents that are checked and signed and double checked and double signed is always being able to get the latest version of a document. And being able to talk to people about what they have written, and get a decision in the case of any ambiguity. this is far more useful to me than anything else.
To sum up: a spec is the only document I have ever found useful, however it pales in comparison to having a project manager who knows the proposed system inside out, and can make sensible decisions based on what they know.
Documentation is like tofu -- most people hate it until they realize that under the right conditions, it can be really good.
The problem is that what you consider documentation is mostly made for documentation's sake. You, as a developer, don't see any immediate value in the documents you produce because you know you can do your job without all the TPS reports which you're required to make.
Unfortunately, I'm going to wager that there's not a lot you can do about in a company where you're being forced to eat raw tofu all the time. You'll probably just have to suck it up and write the docs which your company requires, but you can at least do one thing... you can write documents which at least are useful to you, and you can pass them along with your code for others who will maintain it.
Aside from inline documentation, you could set up a wiki to be used by yourself and people on your team. This type of documentation is searchable, which is already a big plus to developers, plus it's more of a living document instead of a homework-like paper you had to write. You already post to SO, so just think of your documentation as pooling your knowledge in a more useful place.
What do you think are the most important documents for a project?
Different people have different needs: for example the documents which the owner needs (e.g. the business contract) aren't the same as the documents which QA needs.
What documents can be used in the long run by another developer?
IMO the most important document (except for the source code) is the functional specification: because what the software is supposed to do (as opposed to, what it is doing) is the one thing that can't necessarily be reverse-engineered. See also How does a good developer keep from creating code with a low bus hit factor?
User Stories, burndown chart, code
I'm a fan of the old 4+1 views:
Use Case view (a/k/a user stories). There are several forms: proper use cases, forward-looking use cases that aren't as well defined and epics which need to be decomposed.
Logical view. The "static" view. UML Class diagrams and the like work well here as a design document. This also includes request and response formats for various protocols. Here is where we document the RESTful requests and responses. This includes the REST URI design.
Process view. The "dynamic" view. UML activity diagrams, sequence diagrams and statecharts and the like for here for design documents. In some cases, simple narratives work well. In other cases, there's a State design pattern, and it requires a combination of class diagrams and statecharts to show how the stateful objects interact.
This also includes protocols (e.g. REST). Here is where we define any special processing for the various REST requests.
This also includes an authentication or authorization rules, and any other cross-cutting aspects like security, logging, etc.
Component view. The pieces we're building for deployment. This includes the stuff we depend on, the structure of the modules and packages, etc. This is often a simple component diagram or a list of components and their dependencies.
Deployment view. We try to generate this from the code as deployed. Since we're using Python, we use epydoc to create the API documentation. We also use Sphinx to import module documentation into this view of the software.
This also includes the parameters, settings, and configuration details.
This, however, isn't sufficient.
When projects start, you have to work up to this through a series of sprints.
The first sprints build just the use case view.
Subsequent sprints build an "architecture" to implement the use cases. The architecture document has 4+1 views, but at a high level of abstraction. It summarizes the structure of the model schemas, the requests and replies, the RESTful processing, other processing, the expected componentry, etc. It never has a Deployment view. We generally reference operator guide and API documents as the deployment view of an architecture.
Then design-and-construction sprints build (and update) detailed 4+1 view documents for various components.
Then release sprints build (and update) the deployment views.
From the project point of view, the most important documents are those that normally include the word Plan, such as the Project Plan, Configuration Management Plan, Quality Plan, etc.
What you are describing is common in process improvements, and normally responds to two major causes. One is that the system really is overeaching and getting in the way of real work being done. Another is actually answered in your question: it is not that the documents are only done for the sake of audits, and your focus should not just be how usefull is the doc for other developers, but for the project or the company as a whole.
One usually looks at things from it's own perspective, sometimes it's necessary to look at the general picture.